ubuntu下Swagger测试方法

Ubuntu下Swagger测试方法

一环境准备与快速启动

安装基础工具：sudo apt update && sudo apt install -y nodejs npm；验证版本：node -v、npm -v。
方式A Node.js集成：npm i -D swagger-ui-express yamljs；将本地 swagger.yaml/openapi.yaml 加载到 Express，挂载到 /api-docs 后启动服务，浏览器访问 http://localhost:3000/api-docs。
方式B Docker运行Swagger UI：docker pull swaggerapi/swagger-ui:v4.15.5；运行示例：docker run -d -p 38081:8080 swaggerapi/swagger-ui:v4.15.5，访问 http://localhost:38081。如需加载本地规范，使用 -e SWAGGER_JSON 并挂载卷。
方式C 仅编辑文档：docker run -d -p 38080:8080 swaggerapi/swagger-editor:v4.6.0，浏览器访问 http://localhost:38080。

二交互式测试步骤

在Swagger UI中导入或加载你的 swagger.yaml/openapi.yaml。
展开目标接口，点击右侧 Try it out。
填写必要参数：路径参数、查询参数、请求头（如 Content-Type: application/json）、请求体（JSON）。
如接口启用鉴权，点击 Authorize 输入 API Key/Bearer Token。
点击 Execute 查看状态码、响应体、响应头与耗时。

三自动化与CI测试

基于规范的脚本化测试
- Node.js + Supertest：npm i -D mocha chai supertest yamljs；用 supertest 按规范路径发起请求并断言状态码与结构。
- Python + Requests/Pytest：pip install requests pytest pyyaml；读取规范构造请求并断言。
规范一致性/契约测试
- Dredd：npm i -g dredd；执行 dredd swagger.yaml http://localhost:8080，按规范自动发起请求并比对响应。
生成客户端测试
- Swagger Codegen：java -jar swagger-codegen-cli-3.0.44.jar generate -i swagger.yaml -l python -o ./client；用 pytest 编写用例。
命令行与性能
- curl：快速手工验证（GET/POST/Header/Body）。
- ab/siege：基础性能压测。
CI示例（GitHub Actions）
- 运行步骤示例：npm install && npm test 或 pytest；可结合报告与通知。

四常见问题与排查

页面空白/规范加载失败：检查 yaml/json 语法 与文件路径；Docker 方式确认已正确挂载并设置了 SWAGGER_JSON 环境变量。
访问被拒绝/仅本机可访问：服务需监听 0.0.0.0；开放防火墙端口（如 ufw allow 3000/tcp）。
404/401：核对 servers.url 与后端地址一致；涉及鉴权先在 Authorize 填入 Bearer/API Key。
跨域问题：开发阶段在后端启用 CORS；或仅在内网/同域使用 UI。
生产安全：可关闭或限制 /api-docs 访问，或通过 Nginx IP 白名单、鉴权等方式保护文档。

五附最小可用示例

文件结构
- project/
  - server.js
  - swagger.yaml

swagger.yaml（OpenAPI 3.0 片段）

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /hello:
    get:
      summary: 返回问候语
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
servers:
  - url: http://localhost:3000

server.js（Node.js + Express + Swagger UI）

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');
const app = express();
const swaggerDocument = YAML.load('./swagger.yaml');
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
app.get('/hello', (req, res) => res.json({ message: 'Hello, World!' }));
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Server on http://localhost:${PORT}/api-docs`));

运行与测试
- 启动：node server.js；访问 http://localhost:3000/api-docs 使用 Try it out 测试 GET /hello。
- 自动化（示例）：npm i -D mocha chai supertest yamljs；用 supertest 对 /hello 发起 GET 并断言状态码 200 与返回结构。

最新问答

相关标签