如何自定义Debian上的Swagger主题 - 问答

在Debian系统上自定义Swagger（OpenAPI）主题通常涉及修改Swagger UI的静态资源，例如CSS、JavaScript和图像文件。以下是一个基本的步骤指南：

安装Swagger UI：如果你还没有安装Swagger UI，可以通过npm来安装它。首先，确保你已经安装了Node.js和npm。然后，运行以下命令来全局安装Swagger UI：
```
sudo apt update
sudo apt install nodejs npm
sudo npm install -g swagger-ui-express
```
下载Swagger UI：你可以从GitHub上下载Swagger UI的源代码，或者使用npm来获取它。以下是使用npm获取Swagger UI的示例：
```
npm install swagger-ui-dist
```

创建一个简单的Express应用：创建一个新的目录并进入该目录：

mkdir swagger-ui-customization
cd swagger-ui-customization

然后，创建一个 app.js 文件，并添加以下代码来创建一个简单的Express服务器：

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

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

const app = express();

// 使用Swagger UI中间件
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

创建Swagger文档：在项目目录中创建一个 swagger.yaml 文件，并添加你的API文档：

swagger: '2.0'
info:
  title: Sample API
  description: A sample API to demonstrate 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
        format: int64
      name:
        type: string
        email:
          type: string
          format: email

自定义Swagger UI：你可以通过修改 swagger-ui-express 的配置来自定义Swagger UI。例如，你可以更改主题、添加自定义CSS或JavaScript文件等。以下是如何使用预定义主题的示例：

const customUiConfig = {
  deepLinking: true,
  presets: [
    SwaggerUIBundle.presets.apis,
    SwaggerUIStandalonePreset
  ],
  layout: "StandaloneLayout",
  requestInterceptor: (request) => {
    // 自定义请求拦截器
    return request;
  },
  responseInterceptor: (response) => {
    // 自定义响应拦截器
    return response;
  },
  customCssUrl: '/custom-css/custom.css' // 指定自定义CSS文件的路径
};

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, customUiConfig));

运行应用：在终端中运行你的 app.js 文件：
```
node app.js
```
现在，你可以在浏览器中访问 http://localhost:3000/api-docs 来查看自定义后的Swagger UI。

通过这些步骤，你可以在Debian上自定义Swagger UI，以满足你的需求。

0 赞

0 踩