在 koa2 上使用 swagger 自动生成接口文档

swagger 官网介绍 https://swagger.io/

在 koa2 中要想方便快捷使用 swagger，需要安装两个插件

其实这两个插件并没有依赖关系，前者 swagger-jsdoc 的作用是通过手动添加的路由注释生成 json 文档，而后者 koa2-swagger-ui 则基于生成的 json 文档提供强大的交互阅读界面

1.1. 配置步骤

1.1.1. 安装

npm i -D swagger-jsdoc koa2-swagger-ui

1.1.2. 配置 swagger-jsdoc

  1. 首先在项目根目录下新建 swagger.conf.js，示例
const swaggerJSDoc = require("swagger-jsdoc");

const swaggerDefinition = {
  info: {
    // 自定义文档信息
    title: "gallery",
    version: "1.0.0",
    description: "gallery 网站后台 koa api",
  },
  host: `localhost:3000`, // 指定项目地址，建议在环境参数中配置，然后用 process.env 读取
  basePath: "/",
};

const options = {
  swaggerDefinition,
  apis: ["./app/routes/*.js"], // 指定项目路由的相对路径，相对于 basePath
};

const swaggerSpec = swaggerJSDoc(options);

module.exports = swaggerSpec;
  1. 在上述配置文件中导出 swaggerSpec 后，新建一个路由 docs.js，返回该配置文件（其实就是指向了 swagger-jsdoc 生成的 json 文档），此路由返回的文档正是 koa2–swagger-ui 所需的 json 文档
const Router = require("koa-router");
const router = new Router();
const swaggerSpec = require("../../swagger.conf"); // 注意文件路径

// 注意 url 地址，可自定义，在 koa2--swagger-ui 配置中需要引用
router.get("/swaggerDoc", async (ctx) => {
  ctx.body = swaggerSpec;
});

module.exports = router;

1.1.3. 配置 koa2–swagger-ui

  1. 在项目入口文件中配置 koa2–swagger-ui，示例
const Koa = require("koa");
const app = new Koa();
const swagger = require("koa2-swagger-ui");
const routing = require("./routes");

// 开启 swagger 静态服务
app.use(
  swagger({
    routePrefix: "/docs", // 自定义 koa2-swagger-ui 生成的交互界面 url
    swaggerOptions: {
      // 重要选项！url地址一定要指向为 swagger-jsdoc 配置的路由地址
      url: "http://localhost:3000/swaggerDoc",
    },
  })
);

// 路由绑定请自行实现
routing(app);

app.listen(3000, () => {
  console.log("App running at 3000 port");
});

1.2. 文档使用

至此，swagger 的配置就已经全部完成，访问 http://localhost:3000/docs 即可查看 swagger-ui 提供的强大操作界面，接下来只要为各个路由加上注释即可，路由注释规范可参考官网示例 https://github.com/Surnet/swagger-jsdoc/blob/master/example/v2/routes.js