Ubuntu下Swagger UI如何自定义 - 问答

Ubuntu下Swagger UI自定义方法

1. 基础环境准备

在自定义前，需安装Node.js、npm（Node包管理器）和Docker（可选，用于容器化部署）。通过以下命令安装：

sudo apt update
sudo apt install nodejs npm docker.io

2. 安装Swagger UI依赖

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

# 全局安装swagger-ui-express（Express中间件）
sudo npm install -g swagger-ui-express
# 进入项目目录，初始化项目并安装依赖
mkdir swagger-ui-project && cd swagger-ui-project
npm init -y
npm install express swagger-ui-express yamljs

方式二：通过Docker安装（快速部署）

# 拉取Swagger UI官方镜像
docker pull swaggerapi/swagger-ui-express
# 运行容器，映射端口8080
docker run -d -p 8080:8080 swaggerapi/swagger-ui-express

3. 配置Swagger文档

创建Swagger规范文件（swagger.yaml或swagger.json），定义API信息（如路径、方法、参数）。示例swagger.yaml：

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

4. 集成Swagger UI到应用（Node.js项目）

创建app.js文件，使用swagger-ui-express集成Swagger文档：

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

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

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

// 配置Swagger UI选项（自定义入口）
const customOptions = {
  deepLinking: true,          // 启用深度链接
  presets: [
    swaggerUi.presets.apis,   // 默认API预设
    swaggerUi.presets.promises // Promise支持
  ],
  plugins: [
    swaggerUi.plugins.DownloadUrl // 添加下载URL插件
  ],
  layout: "StandaloneLayout"  // 使用独立布局
};

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

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

5. 常见自定义方式

（1）通过配置选项调整UI行为

在swaggerUi.setup()中传入配置对象，可调整以下参数：

deepLinking：启用URL深度链接，支持直接跳转到指定API。
docExpansion：设置文档默认展开状态（none/list/full）。
defaultModelsExpandDepth：默认展开的模型深度（0-10）。
operationsSorter：操作排序方式（alpha按字母排序，method按HTTP方法排序）。

示例：

const customOptions = {
  docExpansion: 'list', // 默认展开所有操作
  operationsSorter: 'alpha', // 按字母排序操作
  defaultModelsExpandDepth: 2 // 默认展开模型到第2层
};

（2）自定义CSS样式

方法一：通过配置注入自定义CSS 在application.yml（Spring Boot项目）或customOptions中添加customCss字段：

springdoc:
  swagger-ui:
    custom-css: |
      .swagger-ui .topbar { background-color: #1E3A8A; }
      .swagger-ui .topbar .download-url-wrapper { display: none; }

方法二：创建自定义CSS文件

在项目静态目录（如src/main/resources/static/）下创建custom-swagger.css：

/* 修改顶部栏背景色 */
.swagger-ui .topbar {
  background-color: #2c3e50 !important;
}
/* 隐藏顶部下载输入框 */
.swagger-ui .topbar .download-url-wrapper {
  display: none !important;
}
/* 修改标题样式 */
.swagger-ui .info .title {
  color: #2c3e50;
  font-size: 36px;
}
/* 修改Try it out按钮 */
.swagger-ui .btn.try-out__btn {
  background-color: #3498db;
  border-color: #3498db;
}

在配置中引用该CSS文件：

springdoc:
  swagger-ui:
    custom-css-url: /custom-swagger.css

（3）完全自定义HTML页面

创建自定义HTML文件（如custom-swagger.html），引入Swagger UI的JS/CSS文件并配置：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>Custom Swagger UI</title>
  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui.css">
  <style>
    body { margin: 0; padding: 0; }
    #custom-header {
      background-color: #2c3e50;
      color: white;
      padding: 20px;
      text-align: center;
    }
    #swagger-ui { max-width: 1200px; margin: 0 auto; }
  </style>
</head>
<body>
  <div id="custom-header">
    <h1>My Custom API Docs</h1>
    <p>Version 1.0.0</p>
  </div>
  <div id="swagger-ui"></div>
  <script src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-bundle.js"></script>
  <script src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-standalone-preset.js"></script>
  <script>
    window.onload = function() {
      const ui = SwaggerUI({
        url: "/v3/api-docs", // 指向后端API文档地址
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUI.presets.apis,
          SwaggerUI.SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUI.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout",
        theme: { // 自定义主题（可选）
          colors: {
            primary: '#2c3e50'
          }
        }
      });
      window.ui = ui;
    };
  </script>
</body>
</html>

（4）使用第三方主题

通过springdoc.swagger-ui.syntax-highlight.theme配置语法高亮主题（如monokai、github）：

springdoc:
  swagger-ui:
    syntax-highlight:
      theme: monokai

（5）添加自定义Logo

在Swagger配置的info部分添加HTML内容，引用Logo图片：

@Bean
public OpenAPI customOpenAPI() {
  return new OpenAPI()
    .info(new Info()
      .title("My API")
      .version("1.0.0")
      .description("<img src='/logo.png' width='100'><br/>My Custom API Documentation")
    );
}

将Logo图片（logo.png）放置在src/main/resources/static/目录下。

6. 运行与验证

Node.js项目：运行node app.js，访问http://localhost:3000/api-docs查看自定义效果。
Docker项目：运行docker run -d -p 8080:8080 swaggerapi/swagger-ui-express，访问http://localhost:8080查看。

注意事项

自定义CSS时，优先使用!important覆盖默认样式（避免被默认样式覆盖）。
完全自定义HTML页面时，需确保正确引入Swagger UI的JS/CSS文件（版本需与依赖一致）。
生产环境中，建议通过Nginx或Apache反向代理Swagger UI，并配置HTTPS以提高安全性。

0 赞

0 踩