Debian系统中Swagger的定制化开发有哪些方法

Debian系统中Swagger定制化开发方法

一 基础环境准备

• 更新系统并安装 Node.js 与 npm（若已安装可跳过）：sudo apt update & & sudo apt install -y nodejs npm。
• 全局安装常用工具：npm install -g swagger-ui-express swagger-jsdoc。
• 准备规范文件：使用 OpenAPI 3.0.0 的 YAML/JSON（如 swagger.yaml 或 openapi.yaml），或采用注解方式在代码中生成。
• 快速验证：启动服务后访问 http://localhost:3000/api-docs 查看文档页面是否正常渲染。

二 定制方向与落地做法

• 文档内容与结构定制
  • 直接编辑 swagger.yaml/swagger.json，补充 info、servers、paths、components/schemas、security 等，确保与后端实现一致。
  • 使用 swagger-jsdoc 从代码注解自动生成规范，减少手工维护成本。
• UI外观与行为定制
  • 通过 swagger-ui-express 的配置项进行界面与交互定制：如 deepLinking、layout、presets、plugins、以及 requestInterceptor/responseInterceptor 等。
  • 引入自定义 CSS/JS：使用 customCss/customJs 或 customCssUrl/customJsUrl 覆盖样式与脚本，实现品牌色、Logo、隐藏元素、扩展按钮等。
• 静态资源与主题深度定制
  • 安装并引用 swagger-ui-dist 静态资源，按需替换内置 CSS/JS/图片，实现主题级深度定制。
• 开发与部署方式
  • 以 Express 托管 UI 与静态资源，适合与现有 Node 服务一体化。
  • 使用 Docker 部署官方镜像（如 swaggerapi/swagger-ui），便于环境一致与快速发布。

三 示例一 Express集成与UI配置

• 安装依赖：npm install express swagger-ui-express swagger-jsdoc yamljs。
• 目录结构建议：项目根目录放置 swagger.yaml，public 目录放置 custom.css/custom.js。
• 示例代码（app.js）：

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

const swaggerDocument = YAML.load('./swagger.yaml');
    

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

// 可选：提供自定义静态资源
app.use('/custom', express.static(path.join(__dirname, 'public')));


app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, {
    
  deepLinking: true,
  layout: 'StandaloneLayout',
  presets: [
    swaggerUi.presets.apis,
    swaggerUi.presets.topbar
  ],
  // 自定义 CSS/JS（URL 指向 /custom 下资源）
  customCssUrl: '/custom/custom.css',
  customJsUrl: '/custom/custom.js',
  // 请求/响应拦截示例
  requestInterceptor: (req) =>
 {
    
    // 例如统一注入认证头
    // req.headers['Authorization'] = 'Bearer <
    your-token>
    ';
    
    return req;

  }

}
    ));
    

app.listen(PORT, () =>
 {

  console.log(`Swagger UI: http://localhost:${
PORT}
    /api-docs`);

}
    );
    

• 运行与验证：node app.js，打开 http://localhost:3000/api-docs 查看效果。

四 示例二 代码注解自动生成规范

• 安装：npm install swagger-jsdoc。
• 配置 swagger-jsdoc（swaggerOptions.js）：

const swaggerJsDoc = require('swagger-jsdoc');


const swaggerOptions = {

  swaggerDefinition: {

    openapi: '3.0.0',
    info: {

      title: 'Debian API',
      version: '1.0.0'
    }
,
    servers: [{
 url: 'http://localhost:3000' }
]
  }
,
  apis: ['./routes/*.js'] // 扫描路由注解
}
    ;
    

const swaggerDocs = swaggerJsDoc(swaggerOptions);
    
module.exports = swaggerDocs;
    

• 在 Express 中使用：

const express = require('express');
    
const swaggerUi = require('swagger-ui-express');
    
const swaggerDocs = require('./swaggerOptions');
    

const app = express();
    
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));
    
app.listen(3000, () =>
     console.log('Docs at http://localhost:3000/api-docs'));
    

• 在路由文件中添加 JSDoc 注解（示例）：

/**
 * @swagger
 * /users:
 *   get:
 *     summary: 获取用户列表
 *     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
 *         name:
 *           type: string
 */
app.get('/users', (req, res) =>
 {
 res.json([{
 id: 1, name: 'Alice' }
    ]);
 }
    );

• 运行后访问 /api-docs 即可看到由注解生成的文档。

五 示例三 Docker化部署与多服务托管

• 使用官方镜像快速启动：

docker pull swaggerapi/swagger-ui
docker run -p 8080:8080 -e SWAGGER_JSON=/spec/openapi.yaml -v $(pwd)/spec:/spec swaggerapi/swagger-ui

• 访问 http://:8080 查看文档。
• 多文档共存（基于 Nginx 反向代理示例，/etc/nginx/sites-available/swagger）：

server {
    
  listen 80;
    
  server_name your-domain;


  location /docs1/ {
    
    proxy_pass http://127.0.0.1:8080/;
    
    proxy_set_header X-Forwarded-Prefix /docs1;

  }

  location /docs2/ {
    
    proxy_pass http://127.0.0.1:8081/;
    
    proxy_set_header X-Forwarded-Prefix /docs2;

  }

}
    

• 将不同规范挂载到不同容器或路径，实现多项目、多版本的文档托管。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！