如何在Linux中使用Swagger UI测试API

在 Linux 中使用 Swagger UI 测试 API 的实用步骤

一 准备与安装

• 使用 Docker 快速启动 Swagger UI（推荐）

  1. 安装 Docker（如未安装）：sudo apt update && sudo apt install -y docker.io && sudo systemctl start docker && sudo systemctl enable docker
  2. 拉取并运行 Swagger UI 容器：
     docker pull swaggerapi/swagger-ui:v4.15.5
     docker run -d -p 38081:8080 swaggerapi/swagger-ui:v4.15.5
  3. 浏览器访问：http://localhost:38081（Swagger UI 首页将自动加载）
     说明：如需同时编辑规范，可另起一个 Editor 容器（示例：docker run -d -p 38080:8080 swaggerapi/swagger-editor:v4.6.0，访问 http://localhost:38080）。

• 使用 Node.js 本地运行 Swagger UI（备选）

  1. 安装 Node.js 与 npm：sudo apt update && sudo apt install -y nodejs npm
  2. 全局安装 Swagger UI 的 Express 封装：npm install -g swagger-ui-express
  3. 创建示例服务（保存为 server.js）：
     const express = require(‘express’); const swaggerUi = require(‘swagger-ui-express’);
     const app = express();
     const swaggerDocument = require(‘./swagger.json’); // 你的 OpenAPI/Swagger 文件
     app.use(‘/api-docs’, swaggerUi.serve, swaggerUi.setup(swaggerDocument));
     app.listen(3000, () => console.log(‘Swagger UI at http://localhost:3000/api-docs’));
  4. 启动服务：node server.js，访问 http://localhost:3000/api-docs。

二 准备 API 规范文件

• 创建 OpenAPI/Swagger 文件（JSON 或 YAML），至少包含：openapi 版本、info 信息、paths 路径与操作、requestBody/parameters、responses 等。示例 swagger.json 片段：
  {
  “openapi”: “3.0.0”,
  “info”: { “title”: “Demo API”, “version”: “1.0.0” },
  “paths”: {
  “/users”: {
  “get”: {
  “summary”: “获取用户列表”,
  “parameters”: [{ “name”: “page”, “in”: “query”, “schema”: { “type”: “integer” }, “required”: false }],
  “responses”: { “200”: { “description”: “OK” } }
  }
  }
  }
  }
• 若使用 Docker 方式，可将 swagger.json 挂载到容器中，并通过环境变量指定 URL：
  docker run -d -p 38081:8080 -e SWAGGER_JSON=/spec/swagger.json -v $PWD:/spec swaggerapi/swagger-ui
  访问 http://localhost:38081 即可看到文档并测试。

三 在 Swagger UI 中测试 API

• 打开 Swagger UI 页面（如 http://localhost:38081 或 http://localhost:3000/api-docs），在页面中浏览到目标接口。
• 点击 Try it out，填写必要的 query/path/header 参数或 requestBody（JSON、form 等）。
• 点击 Execute 发送请求，查看 Status、Response body/headers、耗时等信息。
• 常见要点：
  • 需要鉴权时，在页面的 Authorize 按钮中填入 Bearer Token 或 API Key；
  • 请求体为 JSON 时，设置 Content-Type: application/json；
  • 文件上传使用 multipart/form-data，在参数处选择 file 类型并选取本地文件。

四 常见问题与进阶

• 无法访问页面：确认容器运行（docker ps）、端口映射正确（如 38081:8080），以及云服务器安全组/防火墙已放行对应端口。
• 返回 404/401/415 等：核对接口路径、请求方法、鉴权头、Content-Type 是否与规范一致。
• 规范与代码不一致：在后端集成 Swagger 注解（如 Spring Boot 使用 springfox 或 springdoc-openapi），确保生成的在线文档与实现同步。
• 自动化与性能：Swagger UI 适合手工/交互式调试；可结合 swagger-codegen 生成客户端代码做自动化测试，或用 ab/siege 做基础压力测试。