如何使用 Swagger (OpenAPI) 生成 Koa API 文档？

推荐答案

// www.javascriptcn.com code example
const Koa = require('koa');
const Router = require('koa-router');
const swaggerJSDoc = require('swagger-jsdoc');
const swaggerUI = require('swagger-ui-koa');

const app = new Koa();
const router = new Router();

// Swagger 配置
const swaggerDefinition = {
  openapi: '3.0.0',
  info: {
    title: 'Koa API',
    version: '1.0.0',
    description: 'API documentation for Koa application',
  },
  servers: [
    {
      url: 'http://localhost:3000',
      description: 'Development server',
    },
  ],
};

const options = {
  swaggerDefinition,
  apis: ['./routes/*.js'], // 指定包含 API 文档注释的文件路径
};

const swaggerSpec = swaggerJSDoc(options);

// 添加 Swagger UI 路由
router.get('/swagger.json', async (ctx) => {
  ctx.set('Content-Type', 'application/json');
  ctx.body = swaggerSpec;
});

app.use(swaggerUI.serve);
app.use(router.routes());
app.use(router.allowedMethods());

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

本题详细解读

1. 安装依赖

首先，你需要安装 swagger-jsdoc 和 swagger-ui-koa 这两个包来生成和展示 Swagger 文档。

npm install swagger-jsdoc swagger-ui-koa

2. 配置 Swagger

在代码中，我们定义了一个 swaggerDefinition 对象，它包含了 API 的基本信息，如标题、版本、描述等。servers 字段用于指定 API 的服务器地址。

3. 生成 Swagger 文档

通过 swaggerJSDoc 函数，我们可以生成 Swagger 文档。apis 字段指定了包含 API 文档注释的文件路径。通常，这些注释会写在路由文件中。

4. 添加 Swagger UI 路由

我们创建了一个 /swagger.json 路由，用于返回生成的 Swagger 文档。然后，使用 swaggerUI.serve 中间件来提供 Swagger UI 界面。

5. 启动服务器

最后，启动 Koa 服务器，访问 http://localhost:3000 即可查看生成的 Swagger 文档。

6. 编写 API 文档注释

在路由文件中，你可以使用 JSDoc 注释来描述 API。例如：

// www.javascriptcn.com code example
/**
 * @swagger
 * /users:
 *   get:
 *     summary: 获取用户列表
 *     description: 返回所有用户的列表
 *     responses:
 *       200:
 *         description: 成功获取用户列表
 */
router.get('/users', async (ctx) => {
  ctx.body = { users: [] };
});

通过这种方式，你可以为每个 API 添加详细的文档注释，Swagger 会自动生成相应的文档。