在Ubuntu上Swagger测试如何进行 - 问答

在 Ubuntu 上进行 Swagger 测试

一准备环境

安装 Node.js 与 npm（Swagger Editor/UI 基于 Node 生态）：
- 执行：sudo apt update && sudo apt install -y nodejs npm
可选安装 Docker（便于容器化运行 Editor/UI）：
- 执行：sudo apt install -y docker.io
准备 API 定义文件：建议使用 OpenAPI 2.0/3.x 的 swagger.yaml 或 swagger.json，后续在 UI 中导入或作为服务托管。

二本地启动 Swagger Editor 与 Swagger UI

方式一本地构建运行（npm + http-server）

安装静态服务器：sudo npm install -g http-server

启动 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
http-server -p 8080

启动 UI（示例版本 v3.48.0）：

wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v3.48.0.tar.gz
tar -xvf v3.48.0.tar.gz && cd swagger-ui-3.48.0
npm install
http-server -p 8081

访问：http://localhost:8080（Editor），http://localhost:8081（UI）

方式二使用 Docker（更简洁）

运行 Editor（示例版本 v4.6.0）：

docker pull swaggerapi/swagger-editor:v4.6.0
docker run -d -p 38080:8080 swaggerapi/swagger-editor:v4.6.0

运行 UI（示例版本 v4.15.5）：

docker pull swaggerapi/swagger-ui:v4.15.5
docker run -d -p 38081:8080 swaggerapi/swagger-ui:v4.15.5

访问：http://localhost:38080（Editor），http://localhost:38081/swagger-ui.html（UI）

导入与测试
- 在 Editor 中导入你的 swagger.yaml/json 进行在线编辑与校验
- 在 UI 的地址栏填入你的规范文件 URL 或拖拽文件，点击 Explore；在具体接口上点击 Try it out → 填写参数 → Execute 发起请求。

三将 Swagger UI 集成到你的服务

适用场景：你的后端已在 Ubuntu 上运行，想在同一服务内提供 /api-docs 页面。

步骤（以 Express + swagger-ui-express + YAML 为例）：

安装依赖：

mkdir swagger-demo && cd swagger-demo
npm init -y
npm install express swagger-ui-express yamljs

创建 swagger.yaml（示例片段）：

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List 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));
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Server on ${PORT}, /api-docs`));

启动服务：node index.js，访问 http://localhost:3000/api-docs

提示：如使用 OpenAPI 2.0，将 YAML 头部改为 swagger: '2.0' 并确保字段兼容。

四自动化测试与持续集成

方案 A 代码生成客户端 + 测试框架

使用 swagger-codegen-cli 生成 Python 客户端：

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
java -jar swagger-codegen-cli.jar generate -i http://localhost:3000/v2/api-docs -l python -o ./generated-client

用 pytest + requests 编写并运行测试（示例）：

pip install pytest requests
# test_api.py
import requests
def test_get_users():
    r = requests.get('http://localhost:3000/users')
    assert r.status_code == 200
pytest test_api.py

方案 B Postman Collection + Newman
- 将 Swagger 导出为 Postman Collection JSON，用 Newman 在 CLI/CI 运行：
```
npm install -g newman
newman run your-swagger-collection.json -r cli,json,html
```
方案 C 契约测试工具 Dredd
- 对标 OpenAPI 契约，直接验证服务实现：
```
npm install -g dredd
dredd swagger.yaml http://localhost:3000
```
方案 D 在 Express 中结合 Mocha/Chai/Supertest 做端到端断言测试（适合已有 Node 服务）。

五常见问题与排障

端口占用：更换端口（如 8080→8082），或释放占用进程：sudo lsof -i:8080 → kill <PID>
跨域问题：在后端启用 CORS，或让 UI 与服务同域部署
本机访问不了容器：确认运行 Docker 时映射了端口（如 -p 38081:8080），并使用 http://localhost:38081/swagger-ui.html
规范校验失败：使用 Editor 的 Validate 功能定位 YAML/JSON 语法或结构错误
生产环境安全：限制 /api-docs 访问（如 Nginx IP 白名单、Basic/OAuth2），或在生产关闭文档

0 赞

0 踩