Ubuntu Swagger如何调试API

在Ubuntu上使用Swagger调试API的完整流程

1. 准备基础环境

在Ubuntu上调试Swagger前，需先安装Node.js和npm（Swagger Editor/UI的运行依赖）。打开终端，执行以下命令：

sudo apt update
sudo apt install -y nodejs npm

安装完成后，通过node -v和npm -v验证安装是否成功。

2. 安装Swagger工具

方式一：安装Swagger Editor（在线编辑+调试）

Swagger Editor支持在线编写、预览和调试Swagger规范（YAML/JSON格式）。通过npm全局安装：

npm install -g swagger-editor

安装完成后，启动Editor：

swagger-editor

默认会在http://localhost:9000启动，浏览器访问即可进入编辑界面。

方式二：安装Swagger UI（接口测试界面）

Swagger UI用于可视化测试API接口。通过npm全局安装：

npm install -g swagger-ui-express

若需单独启动Swagger UI（非集成到Express项目），可使用以下命令（需提前下载Swagger UI源码）：

npm install -g swagger-ui
swagger-ui

默认会在http://localhost:8080启动。

3. 配置Swagger文档

生成Swagger规范文件

Swagger调试的核心是Swagger规范文件（swagger.yaml或swagger.json），可通过以下两种方式获取：

手动编写：根据OpenAPI规范编写（推荐使用Swagger Editor的可视化编辑功能）；
自动生成：若已有后端服务（如Spring Boot、Node.js），可通过插件（如springfox-swagger2、swagger-jsdoc）自动生成。

集成到Express项目（可选但推荐）

若需将Swagger UI集成到自己的Express应用中，需创建app.js文件并添加以下代码：

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');

const app = express();
const port = process.env.PORT || 3000;

// 读取Swagger规范文件（需提前创建swagger.yaml）
const swaggerDocument = YAML.load('./swagger.yaml');

// 挂载Swagger UI到/api-docs路径
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

app.listen(port, () => {
  console.log(`Swagger UI is running at http://localhost:${port}/api-docs`);
});

启动Express应用后，通过http://localhost:3000/api-docs访问Swagger UI。

4. 使用Swagger UI调试API

加载规范文件

若集成到Express项目，直接访问http://localhost:3000/api-docs，Swagger UI会自动加载swagger.yaml；
若单独启动Swagger UI，进入界面后点击“Explore”按钮，选择本地的swagger.yaml或输入远程URL（如http://your-server/swagger.yaml）。

测试接口

在Swagger UI界面中，找到需测试的接口（如GET /users），点击接口名称左侧的Try it out按钮；
输入接口参数（如路径参数、查询参数、请求体），点击Execute按钮；
查看Response区域：
- 状态码（如200表示成功，404表示未找到）；
- 响应头（Headers）；
- 响应体（Body，通常为JSON格式）。

5. 高级调试技巧

自定义调试脚本（自动授权/数据处理）

若需自动处理授权（如Bearer Token）或修改请求数据，可在Swagger UI目录下创建custom.js文件，编写自定义函数（如自动添加Token），并通过InjectJavascript机制注入到Swagger UI中间件中。

结合Visual Studio Code调试

若需调试后端代码（如Node.js服务），可使用VS Code的调试功能：

安装VS Code的“Node.js”扩展；

创建launch.json配置文件（位于.vscode目录）：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "program": "${workspaceFolder}/app.js",
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

启动调试：在终端运行node --inspect-brk app.js，然后在VS Code中按下F5开始调试。

使用Docker简化部署

若不想手动安装依赖，可使用Docker快速启动Swagger Editor/UI：

# 拉取Swagger Editor镜像
docker pull swaggerapi/swagger-editor:v4.6.0
# 运行Editor容器（映射端口38080到宿主机8080）
docker run -d -p 38080:8080 swaggerapi/swagger-editor:v4.6.0

# 拉取Swagger UI镜像
docker pull swaggerapi/swagger-ui:v4.15.5
# 运行UI容器（映射端口38081到宿主机8080）
docker run -d -p 38081:8080 swaggerapi/swagger-ui:v4.15.5

访问http://localhost:38080（Editor）或http://localhost:38081（UI）即可使用。

注意事项

若遇到404错误，需检查防火墙设置（允许对应端口，如sudo ufw allow 3000）；
若接口测试失败，需检查Swagger规范文件的正确性（如路径、参数类型）及后端服务的运行状态；
避免使用Ctrl+Z暂停进程，建议使用Ctrl+C终止，防止进程在后台残留。