轻松实现 Swagger UI 文档展示

2023-11-22 08:11:25

前言

在开发 API 接口时，接口文档是必不可少的。它可以帮助开发人员快速了解 API 的功能、参数和返回值，从而提高开发效率。Swagger UI 是一个流行的 API 文档工具，它可以将 API 文档以交互式的方式展示出来，使用起来非常方便。

使用 koa2-swagger-ui 展示 Swagger UI

koa2-swagger-ui 是一个 Koa 2 中间件，它可以将 Swagger UI 渲染到页面上。使用 koa2-swagger-ui 展示 Swagger UI 的步骤如下：

安装 koa2-swagger-ui 中间件：

npm install koa2-swagger-ui

在 Koa 2 应用中使用 koa2-swagger-ui 中间件：

const Koa = require('koa');
const app = new Koa();

const swaggerUi = require('koa2-swagger-ui');
app.use(swaggerUi.koa2({
  routePrefix: '/swagger', // 接口文档访问的路由前缀
  swaggerOptions: {
    url: '/api-docs.json', // 指向 swagger json 文档的地址
  },
}));

运行 Koa 2 应用：

node app.js

访问 /swagger 路由，即可看到 Swagger UI 界面。

使用 Swagger jsdoc 生成 Swagger UI 文档

Swagger jsdoc 是一个库，它可以将注释生成 Swagger UI 文档所需的 JSON 格式文件。使用 Swagger jsdoc 生成 Swagger UI 文档的步骤如下：

安装 Swagger jsdoc 库：

npm install swagger-jsdoc

在项目中创建一个 jsdoc 配置文件（通常是 jsdoc.json）：

{
  "source": {
    "include": ["src/**/*.js"] // 需要生成文档的源代码文件
  },
  "plugins": [
    "plugins/markdown" // 使用 markdown 注释
  ],
  "opts": {
    "destination": "./docs", // 文档生成的目标目录
    "recurse": true, // 是否递归生成子目录的文档
    "template": "node_modules/swagger-jsdoc/templates/html2" // 使用 html2 模板
  }
}