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;
  }
}

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

最新问答

相关标签