Ubuntu 下使用 Swagger 进行功能测试
一 准备与安装
- 安装 Node.js 与 npm：sudo apt update && sudo apt install -y nodejs npm。
- 方式一 本地静态服务：下载并启动 Swagger Editor（示例版本 v3.16.1）与 Swagger UI（示例版本 v3.48.0），分别访问 http://localhost:8080 与 http://localhost:8081。
- 方式二 Docker 快速启动：
- 拉取并运行 Editor：docker pull swaggerapi/swagger-editor:v4.6.0；docker run -d -p 38080:8080 swaggerapi/swagger-editor:v4.6.0
- 拉取并运行 UI：docker pull swaggerapi/swagger-ui:v4.15.5；docker run -d -p 38081:8080 swaggerapi/swagger-ui:v4.15.5
- 说明：Swagger 现已演进为 OpenAPI，以下流程对两者均适用。
二 在 Swagger UI 中进行手工功能测试
- 加载规范：在 Swagger UI 的 Explore 输入框填入你的 swagger.yaml/swagger.json 地址或上传文件，加载 API 定义。
- 发起请求：展开目标 path，点击 Try it out，填写 query/path/header/form 等参数，点击 Execute 查看 状态码、响应体、响应头。
- 认证与授权：如接口需要 API Key/Bearer Token/OAuth2，在 UI 的 Authorize 弹窗中填入凭据后再执行。
- 常见问题：
- 出现 CORS 错误时，后端需开启跨域或配置代理；也可在本地开发环境临时使用代理/浏览器插件绕过。
- 请求体示例建议与 schema 一致，避免 400/422 校验错误。
三 自动化与持续集成测试
- 代码生成 + 单元/集成测试：用 swagger-codegen-cli 生成客户端（如 Python/Java），结合 pytest/JUnit 编写用例并运行，适合强类型校验与业务场景覆盖。
- Postman Collection + Newman：将 Swagger 导出为 Postman Collection，用 Newman 在命令行批量运行并生成 CLI/JSON/HTML 报告，便于 CI/CD 集成。
- Dredd：针对 OpenAPI 的契约测试工具，校验实际响应是否符合规范，一行命令即可跑全量接口。
- Swagger-Tester（Python）：直接读取 Swagger 文件并发起请求，验证响应结构与状态码，适合轻量化自动化回归。
- JMeter：结合 Swagger 元数据生成或手工维护脚本，做功能与性能回归。
四 示例流程 从 Swagger 到自动化测试
- 启动被测服务：确保目标 API 在 http://localhost:8080 提供 OpenAPI JSON（如 /v2/api-docs 或 /v3/api-docs）。
- 启动 Swagger UI（Docker 示例）：docker run -d -p 38081:8080 swaggerapi/swagger-ui:v4.15.5，在浏览器打开 http://localhost:38081，在 Explore 填入 http://localhost:8080/v3/api-docs 完成加载与手工验证。
- 生成客户端并测试（Python 示例）：
- 下载 swagger-codegen-cli-3.0.44.jar；
- 生成客户端：java -jar swagger-codegen-cli.jar generate -i http://localhost:8080/v3/api-docs -l python -o ./generated-client；
- 编写测试（pytest）：
- import requests
def test_get_ping():
r = requests.get(“http://localhost:8080/ping”, timeout=5)
assert r.status_code == 200
- 运行：pytest test_api.py -v。
- 契约测试（Dredd 示例）：npm install -g dredd；dredd swagger.yaml http://localhost:8080（按提示配置 request.headers 等）。
五 常见问题与排查
- 端口与防火墙：确认 8080/38080/38081 等端口已放行（云服务器需配置安全组/防火墙）。
- CORS：开发阶段优先在后端开启 CORS 或使用代理；生产不建议放宽。
- 认证失败：核对 API Key 位置（header/query）、Bearer Token 有效期与 OAuth2 授权码流程。
- 规范与实现不一致：用 Dredd/Swagger-Tester 做契约测试，及时修正接口实现或更新 OpenAPI 文档。
- 报告与可追溯：在 CI/CD 中使用 Newman 生成 HTML/JSON 报告并归档，便于回溯。
