如何在Ubuntu中用Swagger调试代码

在Ubuntu系统中，使用Swagger调试代码的核心流程是安装Swagger工具→配置Swagger文档→启动服务并测试接口→结合调试工具排查问题。以下是详细步骤：

1. 准备工作：安装必要工具

在Ubuntu上使用Swagger前，需安装以下工具：

Node.js与npm：Swagger UI及相关工具依赖Node.js环境。
```
sudo apt update
sudo apt install -y nodejs npm
```

Docker（可选）：若希望通过容器化方式运行Swagger UI，需安装Docker。

sudo apt install -y docker.io
sudo systemctl start docker
sudo systemctl enable docker

2. 安装Swagger UI

Swagger UI是调试API的主要可视化工具，以下是三种常见安装方式：

方式一：通过npm安装（适用于Node.js项目）

# 全局安装swagger-ui-express
sudo npm install -g swagger-ui-express

这种方式需结合Express框架使用，适合已有Node.js项目的场景。

方式二：使用Docker运行（快速部署）

# 拉取Swagger UI镜像
docker pull swaggerapi/swagger-ui

# 运行容器（将本地swagger.json挂载到容器内）
docker run -p 8080:8080 -v /path/to/your/swagger.json:/usr/share/nginx/html/swagger.json swaggerapi/swagger-ui

访问http://localhost:8080即可查看Swagger UI（需将/path/to/your/swagger.json替换为实际路径）。

方式三：直接下载Swagger Editor（离线使用）

# 下载Swagger Editor
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
npm install -g http-server
http-server -p 8080

访问http://localhost:8080，可通过界面编辑或导入Swagger文档（如swagger.yaml/swagger.json）。

3. 创建Swagger文档

Swagger调试需基于API规范文档（支持YAML或JSON格式）。以下是一个简单的swagger.yaml示例：

swagger: '2.0'
info:
  title: Sample API
  description: A demo API for Swagger debugging
  version: 1.0.0
basePath: /
paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: A list of users
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string

将文档保存为swagger.yaml（或swagger.json），并放置在项目根目录。

4. 集成Swagger到应用（Node.js示例）

若使用Node.js框架（如Express），需将Swagger UI集成到应用中，实现文档与接口的联动：

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

const app = express();
const port = 3000;

// 加载Swagger文档
const swaggerDocument = YAML.load('./swagger.yaml');

// 集成Swagger UI（访问/api-docs查看）
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

// 示例接口（需与Swagger文档一致）
app.get('/users', (req, res) => {
  res.json([{ id: 1, name: 'John Doe' }, { id: 2, name: 'Jane Smith' }]);
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

运行应用：

node app.js

访问http://localhost:3000/api-docs，即可看到Swagger UI界面，其中包含/users接口的定义。

5. 调试接口

在Swagger UI界面中，调试接口的步骤如下：

找到目标接口（如/users的GET方法），点击右侧的Try it out按钮。
输入必要的参数（若有），点击Execute按钮。
查看Response区域的结果：
- 若状态码为200，说明接口正常；
- 若出现错误（如404、500），需检查Swagger文档与接口实现的一致性（如路径、参数类型）或后端代码逻辑。

6. 高级调试技巧

使用Visual Studio Code调试：
若需更深入的调试（如查看变量、断点调试），可通过VS Code配置Node.js调试：
1. 在项目根目录创建.vscode/launch.json文件：
```
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Swagger App",
      "program": "${workspaceFolder}/app.js",
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}
```
2. 在VS Code中按下F5，启动调试模式；
3. 在代码中设置断点，通过Swagger UI触发接口请求，查看变量值和调用栈。

自定义Swagger UI：
若需修改Swagger UI样式或添加自动授权功能，可在node_modules/swagger-ui-dist目录下创建custom.js文件，编写自定义脚本（如自动添加Token）：

window.onload = function() {
  const token = 'your_access_token';
  SwaggerUIBundle.authActions.authorize({ 
    token: { value: token } 
  });
};

然后在集成Swagger UI时注入该脚本：

app.use('/api-docs', swaggerUi.serve, (req, res, next) => {
  req.swaggerUiOptions.injectJavascript = '/path/to/custom.js';
  next();
}, swaggerUi.setup(swaggerDocument));

通过以上步骤，你可以在Ubuntu系统中使用Swagger完成API文档的可视化、接口测试及调试。若遇到问题，可检查Swagger文档的语法（如YAML缩进）、接口实现的路径与文档是否一致，或通过调试工具定位具体错误。

如何在Ubuntu中用Swagger调试代码