Ubuntu上Swagger API如何测试

Ubuntu上Swagger API测试实操指南

一准备环境

更新系统并安装 Node.js 与 npm（Swagger Editor/UI 基于 Node 生态）：
- 命令：sudo apt update && sudo apt install -y nodejs npm
可选：安装 Docker（便于用容器快速起 Swagger UI/Editor）：
- 命令：sudo apt install -y docker.io
说明：Swagger 现已演进为 OpenAPI 规范，常见工具为 Swagger Editor（编辑/校验）与 Swagger UI（在线调试）。

二方式一使用Docker快速起Swagger UI

拉取镜像（示例使用 v4.15.5）：docker pull swaggerapi/swagger-ui:v4.15.5
启动容器（将本地 /path/to/swagger.yaml 挂载到容器内并指定服务器地址）：
- 命令：
```
docker run -d --name swagger-ui \
  -p 38081:8080 \
  -e SWAGGER_JSON=/spec/swagger.yaml \
  -v /path/to:/spec \
  swaggerapi/swagger-ui:v4.15.5
```
- 访问：http://localhost:38081/swagger-ui.html
- 提示：在 Swagger UI 的 Servers 处将服务器地址设置为你的后端地址（如 http://host.docker.internal:3000 或实际服务地址），否则可能请求到容器内部空地址。

三方式二在Node应用中集成Swagger UI

初始化项目并安装依赖：
- 命令：mkdir swagger-demo && cd swagger-demo && npm init -y
- 安装：npm i express swagger-ui-express yamljs

创建 swagger.yaml（示例）：

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
servers:
  - url: http://localhost:3000
paths:
  /users:
    get:
      summary: List all users
      responses:
        '200':
          description: OK

创建 index.js：

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('/users', (req, res) => res.json([{ id: 1, name: 'Alice' }]));
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Server on ${PORT}, /api-docs`));

启动与访问：
- 启动：node index.js
- 访问：http://localhost:3000/api-docs，在页面中点击 Try it out 发起请求。

四方式三使用Swagger Editor编辑与验证

下载并启动（示例版本 v3.16.1）：

wget https://github.com/swagger-api/swagger-editor/archive/refs/tags/v3.16.1.tar.gz
tar -xvf v3.16.1.tar.gz
cd swagger-editor-3.16.1
npm install
npx http-server -p 8080

访问：http://localhost:8080，导入你的 swagger.yaml/swagger.json 进行校验与调试。
说明：Swagger Editor 主要用于编辑与校验规范，实际发起请求建议用 Swagger UI 或与后端联调。

五常见问题与自动化测试

常见问题
- 端口占用：更换 -p 端口或停止占用进程（如 lsof -i:8080）。
- CORS 跨域：开发环境在后端启用 CORS；Swagger UI 容器场景优先用 host.docker.internal 指向宿主机服务。
- 访问被拒绝：检查 防火墙/云安全组 是否放行对应端口（如 8080/3000/38081）。
- 路径 404：确认后端服务已启动且 servers.url 配置正确；容器内外地址映射无误。

自动化测试示例（Node + Mocha + Supertest）

安装：npm i -D mocha chai supertest yamljs

测试脚本 test-swagger.js：

const request = require('supertest');
const app = require('./index'); // 上面的 Express 实例
const { expect } = require('chai');

describe('GET /users', () => {
  it('should return 200 and an array', async () => {
    const res = await request(app).get('/users');
    expect(res.status).to.equal(200);
    expect(res.body).to.be.an('array');
  });
});

运行：npx mocha test-swagger.js

其他工具
- 使用 swagger-tester（Python）对规范进行自动化校验与示例请求验证：
  - 安装：pip install swagger-tester
  - 使用：from swagger_tester import swagger_test; swagger_test(‘path/to/swagger.yaml’)。

最新问答

相关标签