使用 Swagger UI 生成 RESTful API 文档-JavaScript中文网-JavaScript教程资源分享门户

前言

在前端开发过程中，后端接口可谓是必不可少的一部分。而随着 RESTful API 的普及，其规范性和可维护性也越来越受到重视。然而，对于接口规范的撰写和维护往往会耗费大量的时间和精力，影响开发效率。这时候，Swagger UI 就成了一个强大的工具，可以快速生成 RESTful API 文档，提升接口管理的效率。

什么是 Swagger UI

Swagger UI 是一款开源的基于 OpenAPI 规范的 API 文档生成工具，它提供了一系列的界面功能，让开发者可以直观地查看和测试 API 接口，同时也方便了接口规范的编写和维护。

Swagger UI 的优势

规范性强 ：Swagger UI 遵循 OpenAPI 规范，确保接口文档的规范性和可维护性。
易于使用 ：Swagger UI 可以快速生成接口文档，并提供丰富的界面功能，方便了开发者的使用和测试。
可定制化 ：Swagger UI 提供了一系列的主题和配置项，可以根据自己的需求进行定制。

Swagger UI 的使用

步骤一：安装 Swagger UI

通过 npm 安装：

npm install swagger-ui-express swagger-jsdoc --save

步骤二：编写接口规范文件

使用 OpenAPI 规范编写接口规范文件，例如 swagger.yaml 或 swagger.json 文件。

步骤三：生成接口文档

在后端项目中调用 Swagger UI 并指定接口规范文件的路径即可。

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerJSDoc = require('swagger-jsdoc');

const app = express();

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'My API',
      version: '1.0.0',
    },
  },
  apis: ['./routes/*.js'],
};

const swaggerSpec = swaggerJSDoc(options);

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

app.listen(3000, () => {
  console.log('Server started on http://localhost:3000');
});

这里我们使用了 swaggerJSDoc 和 swagger-ui-express 两个 npm 包，前者用于将接口规范文件解析为 Swagger UI 能识别的格式，后者则是用于提供 Swagger UI 界面的 express 中间件。

步骤四：访问 Swagger UI 界面

在浏览器中输入 http://localhost:3000/api-docs 即可访问 Swagger UI 界面。可以看到 Swagger UI 生成了清晰明了的接口文档，并提供了一些界面功能，例如查看参数、测试接口等。

Swagger UI 的定制化

Swagger UI 提供了许多主题和配置项，可以根据自己的需求进行定制。下面我们简单介绍一下 Swagger UI 的主题和配置项。

主题

Swagger UI 支持多种主题，包括默认主题、官方主题和许多第三方主题等。其中默认主题是 Swagger UI 自带的主题，而官方主题可以从 https://github.com/swagger-api/swagger-ui/tree/master/packages/swagger-ui-themes 中下载。

在使用时，只需在 Swagger UI 的配置项中指定主题即可。例如：

const swaggerUi = require('swagger-ui-express');
const swaggerJSDoc = require('swagger-jsdoc');
const customTheme = require('./custom-theme.js');

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'My API',
      version: '1.0.0',
    },
  },
  apis: ['./routes/*.js'],
  swaggerOptions: {
    theme: customTheme,
  },
};
const swaggerSpec = swaggerJSDoc(options);

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

配置项

Swagger UI 还提供了许多配置项，可以满足不同的需求。下面我们介绍一些常用的配置项。

隐藏 API 文档中的 header 和 footer

const options = {
  ...
  swaggerOptions: {
    displayRequestDuration: true,
    docExpansion: 'none',
    defaultModelRendering: 'example',
    supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
    showRequestHeaders: false,
    showOperationIds: false,
    showExtensions: false,
  },
};

去除掉 Swagger UI 注释中的 iframe

const options = {
  ...
  swaggerOptions: {
    filter: true,
  },
};

其他配置项

const options = {
  ...
  swaggerOptions: {
    deepLinking: true,
    displayRequestDuration: false,
    docExpansion: 'none',
    filter: true,
    maxDisplayedTags: 5,
    operationsSorter: 'alpha',
    showExtensions: true,
    tagsSorter: 'alpha',
    validatorUrl: null,
    supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
  },
};

总结

Swagger UI 是一款非常好用的 RESTful API 文档生成工具，具有规范性强、易于使用、可定制化等优点。通过使用 Swagger UI，我们可以快速生成接口文档，提升接口管理的效率。期待读者在实践中得到进一步的收获。

示例代码：https://github.com/XiangWys/swagger-ui-example

来源：JavaScript中文网，转载请注明来源本文地址：https://www.javascriptcn.com/post/659e1b7aadd4f0e0ff730ce2

使用 Swagger UI 生成 RESTful API 文档

前言