如何在Debian中自定义Swagger文档

在Debian中自定义Swagger文档的完整步骤

1. 准备系统环境

首先确保Debian系统已更新，并安装Node.js、npm（Node.js包管理器）等基础依赖，用于后续Swagger UI的安装与配置：

sudo apt update && sudo apt upgrade -y
sudo apt install -y nodejs npm

2. 安装Swagger UI及相关依赖

通过npm全局安装swagger-ui-express（用于将Swagger文档集成到Express应用）和yamljs（用于解析YAML格式的Swagger文档）：

sudo npm install -g swagger-ui-express yamljs

3. 创建Express应用框架

新建一个项目目录，初始化Express应用并配置Swagger文档的加载与展示：

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

创建app.js文件，编写以下核心代码：

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

// 加载Swagger文档（需提前创建swagger.yaml）
const swaggerDocument = YAML.load('./swagger.yaml');

const app = express();

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

// 启动服务器（默认端口3000）
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Swagger UI已启动，访问地址：http://localhost:${PORT}/api-docs`);
});

4. 编写Swagger文档（YAML格式）

在项目根目录创建swagger.yaml文件，定义API的基本信息、路径、参数及响应等。以下是一个示例：

openapi: 3.0.0
info:
  title: Debian自定义Swagger文档示例
  description: 通过Debian系统自定义Swagger UI的配置教程
  version: 1.0.0
servers:
  - url: http://localhost:3000
    description: 本地开发服务器
paths:
  /users:
    get:
      summary: 获取用户列表
      description: 返回系统中的所有用户信息
      responses:
        '200':
          description: 用户列表获取成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: 用户唯一标识
        name:
          type: string
          description: 用户姓名
        email:
          type: string
          format: email
          description: 用户邮箱

5. 自定义Swagger UI的方法

（1）修改Swagger文档内容

直接编辑swagger.yaml文件，调整API的描述、路径、参数或响应结构。例如，添加新的路径/users/{id}用于获取单个用户信息：

paths:
  /users/{id}:
    get:
      summary: 获取指定ID的用户信息
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 用户信息获取成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

（2）调整Swagger UI配置

在app.js中，通过swaggerUi.setup()方法的配置参数自定义UI行为。例如：

启用深度链接：允许直接跳转到具体路径；
设置布局：使用StandaloneLayout提升界面体验；
添加请求拦截器：修改请求头（如添加认证信息）。

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, {
  deepLinking: true, // 启用深度链接
  layout: 'StandaloneLayout', // 使用独立布局
  requestInterceptor: (request) => {
    // 在请求头中添加认证Token（示例）
    request.headers['Authorization'] = 'Bearer your_token_here';
    return request;
  }
}));

（3）覆盖静态资源（自定义CSS/JS）

若需修改Swagger UI的外观或添加自定义功能，可以覆盖其默认静态资源：

在项目根目录创建public文件夹，用于存放自定义文件；
在public/css下创建custom.css，修改主题颜色（例如将导航栏背景改为深蓝色）：
```
.swagger-ui .topbar {
  background-color: #2c3e50 !important;
}
```

在app.js中配置静态资源路径，将自定义文件映射到Swagger UI：

app.use('/custom-css', express.static(path.join(__dirname, 'public/css')));
// 在Swagger配置中引用自定义CSS
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, {
  customCss: '/custom-css/custom.css'
}));

6. 运行并验证自定义效果

启动Express应用：

node app.js

打开浏览器访问http://localhost:3000/api-docs，即可看到自定义后的Swagger UI界面。此时，你可以通过修改swagger.yaml文档内容或调整app.js中的配置，实时查看界面的变化。

通过以上步骤，你可以在Debian系统中完成Swagger文档的自定义，包括内容调整、界面优化及功能扩展，满足API文档的个性化需求。