centos swagger API测试方法

CentOS 上 Swagger API 测试方法

一 准备与快速接入

• 使用 Docker 快速起服务（推荐）
  • 启动编辑器：docker run -d -p 38080:8080 swaggerapi/swagger-editor:v4.6.0
  • 启动展示页：docker run -d -p 38081:8080 swaggerapi/swagger-ui:v4.15.5
  • 访问：Editor 在 http://<服务器IP>:38080，UI 在 http://<服务器IP>:38081
• 本机无桌面环境时，优先用 Docker 或命令行工具，减少依赖问题。

二 在 Swagger UI 中直接测试

• 将你的 swagger.json / swagger.yaml 放到可被访问的位置（如本机 /opt/swagger/public/swagger.json），在 UI 页面把 URL 指向该文件并加载。
• 在 UI 中点击 Try it out，填写参数后执行，查看 状态码、响应体、响应时间。
• 常见故障与处理
  • CORS 报错：在后端添加跨域头，例如：
    • Access-Control-Allow-Origin: *（或指定域名）
    • Access-Control-Allow-Methods: GET,POST,PUT,DELETE,OPTIONS
    • Access-Control-Allow-Headers: Content-Type,Authorization
  • 访问不到文档：检查 防火墙/安全组 是否放行对应端口（如 38080/38081）。

三 命令行与自动化测试

• 使用 curl 复核 UI 发出的请求，便于在终端回归与纳入 CI
  • GET 查询：curl “http://172.16.110.147:9090/client/selectByPage?limit=10&page=1”
  • POST 表单：curl -X POST “http://172.16.110.147:9090/factory/insert” -H “Content-Type: application/x-www-form-urlencoded” -d “factoryName=TestFactory&no=123&remark=TestRemark”
  • POST JSON：curl -X POST “http://172.16.110.147:9090/material/selectAll” -H “Content-Type: application/json” -d ‘{“factory”:“TestFactory”,“materialName”:“TestMaterial”,“materialNo”:“12345”,“offset”:0,“page”:1,“pageSize”:10}’
  • 上传文件：curl -X POST “http://172.16.110.147:9090/api/all/order/money” -F “file=@/path/to/file” -F “startTime=2020-01-01” -F “endTime=2020-06-30”
• 其他常用工具
  • Postman/SoapUI：支持 导入 OpenAPI/Swagger 定义后批量运行用例、断言与报告。
  • Swagger Codegen：从规范 生成客户端/服务端桩代码，便于构造边界与回归测试。
  • 安全回归：在受控环境可用 swagger-hacker.py 做可用性探测，配合 Burp Suite/X-Ray 做深入安全扫描（务必合法合规）。

四 以 swagger-codegen 为例的自动化测试流程

• 安装：npm install -g swagger-codegen
• 从规范生成客户端（示例）
  • swagger-codegen generate -i http://:/swagger.json -l python -o ./client
• 在测试代码中读取 spec 并做契约/回归测试（伪代码）
  • spec = load_spec(“http://:/swagger.json”)
  • for path, ops in spec[“paths”].items():
    • for method, meta in ops.items():
      • resp = client.request(method, path, **sample_params(meta))
      • assert resp.status in meta.get(“responses”, {})
• 适合做 契约测试 与 批量回归，减少手工点击成本。

五 进阶 用 go-swagger 本地托管并测试

• 适用于后端使用 go-zero 等框架的项目
  • 生成文档：goctl api plugin -plugin goctl-swagger=“swagger -filename bookstore.json -host 192.168.99.196:8088 -basepath /” -api bookstore.api -dir .
  • 本地托管文档：./swagger_linux_amd64 serve -F=swagger bookstore.json --port 9088 --host 0.0.0.0 --no-open
  • 访问测试：http://192.168.99.196:9088/docs
  • 若出现 CORS，给后端增加响应头（如 Access-Control-Allow-Origin）。