在 Koa.js 中使用 Swagger 构建 API 文档-JavaScript中文网-JavaScript教程资源分享门户

前言

在现代的互联网应用中，API 文档变得越来越重要。它不仅作为开发者了解和使用 API 的重要工具，还可以为不同部门之间的沟通提供便利。API 文档的编写一直是非常耗时的工作，有时候一个 API 的编写需要好几天甚至几周的时间。但有了 Swagger，这个问题得到了很好的解决。

Swagger 是一个流行的 API 文档工具，它可以自动生成文档，并且为 API 提供交互式的测试功能。在本文中，我们将介绍如何在 Koa.js 中使用 Swagger。

安装 Swagger

首先，我们需要将 Swagger 安装到我们的项目中。使用以下命令：

npm install swagger-jsdoc swagger-ui-koa --save

swagger-jsdoc 是一个基于注释的文档生成器，它允许开发者编写注释，这些注释可以用来生成 Swagger 文档。swagger-ui-koa 是 Swagger 的 UI，可以让我们通过浏览器访问 API 文档。

创建 Swagger 注释

在我们的 Koa.js 应用程序中，我们需要在每个路由处理程序中添加 Swagger 注释。下面是一个简单的示例：

// javascriptcn.com 代码示例
/**
 * @swagger
 * /pets:
 *   get:
 *     tags:
 *       - pets
 *     description: Returns all pets from the system
 *     produces:
 *       - application/json
 *     responses:
 *       200:
 *         description: An array of pets.
 *         schema:
 *           type: array
 *           items:
 *             $ref: '#/definitions/Pet'
 */  

router.get('/pets', async ctx => {
  ctx.body = await Pet.find()
})

注释中的 @swagger 标签指示 Swagger，这是一个 API 文档。其中的 /pets 表示这是一个路由路径，get 表示这个路由路径所使用的 HTTP 动词。其他标签，如 description、produces 和 responses 分别描述了 API 的描述、返回类型和可能返回的状态码。

创建 Swagger 配置

在我们的 Koa.js 应用程序中，我们还需要创建一个 Swagger 配置。这个配置将告诉 Swagger 哪些标签用来生成文档。

下面是一个示例配置文件：

// javascriptcn.com 代码示例
const swaggerJSDoc = require('swagger-jsdoc')

const options = {
  swaggerDefinition: {
    info: {
      title: 'Petstore API',
      version: '1.0.0',
      description: 'A simple API for managing pets'
    },
    basePath: '/'
  },
  apis: ['./routes/*.js']
}

const swaggerSpec = swaggerJSDoc(options)

module.exports = {
  swaggerSpec
}

我们在这里定义了 API 的基本信息，如标题、版本和描述。我们还将基本路径设置为 /。在 apis 列表中，我们列举了应用程序中包含 Swagger 注释的文件路径。

我们将生成的 Swagger 规范导出到 swaggerSpec 中，以便我们可以轻松地将其用于 Swagger UI。

插入 Swagger UI

用 Koa 编写的应用程序中，我们可以通过将 swagger-ui-koa 插入到应用程序中来添加 Swagger UI。

以下是一个示例：

// javascriptcn.com 代码示例
const Koa = require('koa')
const Router = require('koa-router')
const swaggerUiKoa = require('swagger-ui-koa')
const { swaggerSpec } = require('./config/swagger')

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

router.get('/swagger.json', async ctx => {
  ctx.body = swaggerSpec
})

app.use(router.routes())
app.use(router.allowedMethods())

app.use(swaggerUiKoa({ routePrefix: '/docs', swaggerOptions: { spec: swaggerSpec } }))

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

在此示例中，我们将 Swagger 定义注册为 /swagger.json 路由。我们还向端点添加了 Swagger UI，将其挂接到 /docs 路由上。

总结

在本文中，我们详细介绍了如何在 Koa.js 中使用 Swagger 构建 API 文档。我们介绍了 Swagger 的基本概念，包括如何为路由处理程序添加 Swagger 注释。我们还介绍了如何将 Swagger UI 集成到基于 Koa 的应用程序中。我们希望这篇文章能够帮助您了解如何使用 Swagger 来改善您的 API 文档编写过程。

参考资料

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