Debian中Swagger UI如何自定义展示

2025年7月18日 互联网

在Debian系统中自定义Swagger UI的展示，通常涉及以下几个步骤：

  1. 安装Swagger UI：
    首先，你需要在Debian系统上安装Swagger UI。这可以通过npm（Node.js的包管理器）来完成。如果你还没有安装Node.js和npm，请先安装它们。

    sudo apt update
sudo apt install nodejs npm
sudo npm install -g swagger-ui-express

  2. 获取Swagger JSON文件：
    Swagger UI需要一个Swagger JSON文件来展示API文档。这个文件通常是由你的后端服务生成的。确保你有一个有效的Swagger JSON文件。

  3. 启动Swagger UI：
    使用swagger-ui-express模块，你可以很容易地启动一个Swagger UI服务器。创建一个新的JavaScript文件，比如swaggerServer.js，并添加以下代码：

    const express = require('express');
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');
// 读取Swagger JSON文件
const swaggerDocument = YAML.load('./path/to/swagger.json');
const app = express();
// 使用swagger-ui-express中间件
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
const port = process.env.PORT || 3000;
app.listen(port, () => {
  console.log(`Swagger UI is running at http://localhost:${port}/api-docs`);
});

    替换./path/to/swagger.json为你的Swagger JSON文件的实际路径。

  4. 定制Swagger界面：
    Swagger UI提供了一些选项来自定义界面，比如更改主题、布局和显示选项。你可以在swaggerUi.setup()函数中传递一个配置对象来实现这些定制。例如，要更改主题，你可以这样做：

    app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, {
  deepLinking: true,
  presets: [swaggerUi.presets.apis, swaggerUi.presets.topbar],
  plugins: [swaggerUi.plugins.DownloadUrl],
  layout: "StandaloneLayout", // 使用独立布局
  requestInterceptor: (request) => {
    // 在这里可以修改请求
    return request;
  }
}));

    你可以查看Swagger UI的官方文档来了解更多关于定制选项的信息。

  5. 运行你的Swagger UI服务器：
    在终端中运行你的swaggerServer.js文件：

    node swaggerServer.js

    现在，你应该能够在浏览器中访问http://localhost:3000/api-docs来查看定制后的Swagger界面。

通过以上步骤，你可以在Debian系统上成功自定义Swagger UI的主题和样式。

最新文章