如何使用Debian Swagger进行API测试

在 Debian 上进行 Swagger OpenAPI API 测试

一准备环境与规范文件

更新系统并安装常用工具：sudo apt update && sudo apt install -y curl docker.io nodejs npm python3 python3-pip。
准备 API 规范文件：确保有 swagger.json 或 swagger.yaml（OpenAPI/Swagger 描述文件），后续用于生成文档、客户端或驱动自动化测试。

二方式一使用 Swagger UI 进行手工测试

本地快速启动 Swagger UI（Docker）：
- 拉取并运行：docker pull swaggerapi/swagger-ui && docker run -d -p 38081:8080 swaggerapi/swagger-ui
- 在浏览器访问：http://localhost:38081，将你的 swagger.json 通过页面导入或在启动时挂载到容器，即可在 UI 中直接 Try it out 发起请求。
在你的 Node.js 服务中内嵌 Swagger UI（便于与后端同域调试）：
- 安装：npm i express swagger-ui-express [yamljs]
- 示例代码（保存为 server.js）：
  - const express = require(‘express’); const swaggerUi = require(‘swagger-ui-express’); const YAML = require(‘yamljs’);
  - const swaggerDocument = YAML.load(‘./swagger.yaml’);
  - const app = express(); app.use(‘/api-docs’, swaggerUi.serve, swaggerUi.setup(swaggerDocument));
  - app.listen(3000, () => console.log(‘Server on http://localhost:3000/api-docs’));
- 启动服务：node server.js，访问 http://localhost:3000/api-docs 进行手工测试。

三方式二自动化测试方案

方案A 生成客户端 SDK 并编写测试
- 安装 Swagger Codegen CLI（Java 方式，稳定通用）：
  - wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.44/swagger-codegen-cli-3.0.44.jar -O swagger-codegen-cli.jar
- 生成客户端（示例为 python）：
  - java -jar swagger-codegen-cli.jar generate -i http://localhost:8080/v2/api-docs -l python -o ./generated-client
- 使用 pytest/requests 编写测试（示例 test_api.py）：
  - import pytest, requests
  - def test_get_users(): r = requests.get(‘http://localhost:8080/api/users’); assert r.status_code == 200
  - def test_create_user(): d = {“name”:“John Doe”,“email”:“john@example.com”}; r = requests.post(‘http://localhost:8080/api/users’, json=d); assert r.status_code == 201
- 运行：pytest test_api.py。
方案B 使用 Postman Newman 运行集合
- 将 Swagger 导出为 Postman Collection JSON，然后用 Newman 在 CLI 执行：
  - npm install -g newman
  - newman run your-swagger-collection.json -r cli,json,html（生成控制台、JSON、HTML 报告）。
方案C 使用 Dredd 对 OpenAPI 进行契约测试
- 安装：npm install -g dredd
- 执行：dredd swagger.yaml http://localhost:8080（按规范校验实际服务实现）。

四在 CI/CD 中集成

将测试纳入流水线（示例）：
- 构建阶段启动被测服务与 Mock/依赖。
- 运行自动化测试：pytest、newman 或 dredd。
- 归档报告（JUnit/JSON/HTML），设置失败阈值，阻止不合规合并。
参考实践：将生成的客户端测试脚本或 Newman 集合在 GitHub Actions/GitLab CI 中定时或按提交触发执行。

五常见问题与排查

访问被拒绝或 404：确认目标服务已启动且规范中的 basePath 与实际路径一致；必要时在 Swagger UI 的 Servers 配置正确的 Base URL。
认证失败：在 UI 的 Authorize 填入 Bearer Token 或 API Key，或在 curl/Newman 中添加 -H “Authorization: Bearer ”。
规范与实现不一致：使用 Dredd 做契约测试，快速定位缺失或类型不匹配的接口。
本地文件无法加载：若使用文件方式加载 swagger.yaml，注意 YAML 缩进与引用路径；使用 Docker 时可通过卷挂载规范文件到容器内。

最新问答