在CentOS上测试Swagger的可行路径
- 使用容器快速起一个可交互的 Swagger Editor/UI 做文档校验与手工测试。
- 将你的 OpenAPI/Swagger 规范 导出为 Postman Collection，用 Newman 在命令行做自动化回归。
- 用 Dredd 对线上/测试环境的实际服务进行契约/端到端一致性校验。
- 用 Swagger Codegen 生成客户端 SDK，在测试代码中直接调用接口进行场景化测试。
前置准备
- 安装工具与运行环境
- 安装 Docker（推荐）：sudo yum install -y docker && sudo systemctl start docker && sudo systemctl enable docker
- 安装 Node.js/npm（用于 Newman/Dredd 等）：sudo yum install -y nodejs npm
- 安装 Java 8+（用于 Swagger Codegen CLI）：sudo yum install -y java-11-openjdk
- 防火墙放行端口（示例为 8080/38080/38081/3000）：sudo firewall-cmd --permanent --add-port={8080,38080,38081,3000}/tcp && sudo firewall-cmd --reload
- 准备你的 OpenAPI/Swagger 文件（如 swagger.yaml 或 swagger.json），并确保目标 API 服务已在 http://: 可达
方式一 容器化快速测试 Swagger Editor 与 UI
- 启动 Swagger Editor（浏览器中编辑/验证规范）
- docker run -d -p 38080:8080 swaggerapi/swagger-editor:v4.6.0
- 访问：http://<服务器IP>:38080
- 启动 Swagger UI（加载你的规范进行手工测试）
- docker run -d -p 38081:8080 -e SWAGGER_JSON=/spec/swagger.yaml -v /opt/swagger:/spec swaggerapi/swagger-ui:v4.15.5
- 访问：http://<服务器IP>:38081（会自动加载 /spec/swagger.yaml）
- 说明：将 /opt/swagger/swagger.yaml 替换为你的规范路径即可；UI 中可直接 Try it out 发起请求，便于快速手工回归与兼容性验证
方式二 自动化测试与持续集成
- Newman（基于 Postman Collection 的 CLI 自动化）
- 导出：在 Swagger Editor 中选择 Export → Postman Collection v2.1，保存为 collection.json
- 安装：npm install -g newman
- 运行：newman run collection.json -r cli,json,html --reporter-json-export report.json --reporter-html-export report.html
- CI 建议：在 Jenkins/GitHub Actions 中执行，并归档 HTML/JSON 报告
- Dredd（契约测试，校验服务实现是否符合 OpenAPI）
- 安装：npm install -g dredd
- 运行：dredd swagger.yaml http://: --reporter cli --output report.txt
- 适用：对线上/预发环境的真实接口进行“规范 vs 实现”的一致性校验
- Swagger Codegen（生成客户端 SDK 后做场景化测试）
- 下载 CLI（示例版本 3.0.44）：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://:/v2/api-docs -l python -o ./generated-client
- 使用 pytest/requests 或 JUnit 编写测试，覆盖关键业务路径与异常场景
方式三 在目标应用中启用 Swagger UI 并做联调
- Spring Boot 项目示例
- 依赖（Maven）：springfox-swagger2 与 springfox-swagger-ui
- 配置：@Configuration + @EnableSwagger2，定义 Docket Bean（扫描基础包、路径匹配规则等）
- 访问：http://:/swagger-ui.html（或 /swagger-ui/），在页面中直接执行接口
- 其他语言/框架
- 使用 swagger-ui-express（Node.js/Express）：pip3 install swagger-ui-express 或在 Express 中挂载 swagger-ui 静态资源与 JSON 端点
- 使用 Flask-Swagger-UI：Flask 应用注册 swaggerui_blueprint，指向你的 JSON/YAML 规范
- 提示：若前端与后端跨域，需在 API 服务添加 CORS 头（如 Access-Control-Allow-Origin）
常见问题与排查要点
- 访问不到页面：检查 firewalld/安全组 是否放行对应端口，云服务器需开放入站规则
- CORS 错误：在 API 服务添加跨域头，或使用同域代理/网关转发
- 规范校验失败：用 Swagger Editor 先做语法/结构校验，再导出 Collection 或用于 Dredd
- 容器无法加载本地规范：确认 -v 挂载路径 与容器内 SWAGGER_JSON 路径一致，文件权限正确
- 报告与留存：Newman/Dredd 建议输出 HTML/JSON 报告，便于审计与回溯
- 安全建议：生产环境为 Swagger UI/Editor 增加 鉴权/访问控制，避免暴露敏感接口文档与调试入口
