如何在 Fastify 框架中集成 Swagger 文档？

Fastify 是一个快速、低开销和可扩展的 Node.js web 框架。它以高效的方式处理请求，并提供了许多插件来扩展功能。其中一个流行的插件是 Swagger，它可以帮助我们自动生成 API 文档。本文将介绍如何在 Fastify 框架中集成 Swagger 文档。

安装 Swagger

在开始之前，我们需要安装 Swagger 插件。可以使用 npm 命令进行安装：

npm install fastify-swagger --save

配置 Swagger

安装 Swagger 插件后，我们需要配置它。下面是一个示例配置：

const fastify = require('fastify')()
const swagger = require('fastify-swagger')

fastify.register(swagger, {
  routePrefix: '/documentation',
  swagger: {
    info: {
      title: 'Fastify API',
      description: 'API documentation',
      version: '0.1.0'
    },
    externalDocs: {
      url: 'https://swagger.io',
      description: 'Find more info here'
    },
    consumes: ['application/json'],
    produces: ['application/json'],
  },
  exposeRoute: true
})

在上面的代码中，我们将 Swagger 注册为 Fastify 插件，并传递了一些配置选项。其中，routePrefix 用于指定 Swagger UI 的路由前缀，默认为 /documentation。swagger 选项中包含了 API 文档的基本信息，如标题、描述和版本号等。consumes 和 produces 选项用于指定 API 支持的请求和响应格式。最后，exposeRoute 选项用于启用 Swagger UI 页面的路由。

编写 API 文档

我们已经完成了 Swagger 的配置，现在需要编写 API 文档。我们可以使用 fastify-swagger 插件提供的 swagger 装饰器来编写 API 文档。下面是一个示例代码：

fastify.get('/user/:id', {
  schema: {
    description: 'Get user by ID',
    tags: ['user'],
    params: {
      type: 'object',
      properties: {
        id: {
          type: 'integer',
          description: 'User ID'
        }
      }
    },
    response: {
      200: {
        description: 'Successful response',
        type: 'object',
        properties: {
          id: { type: 'integer' },
          name: { type: 'string' },
          email: { type: 'string' }
        }
      }
    }
  }
}, async (request, reply) => {
  const { id } = request.params
  const user = await getUserById(id)
  reply.send(user)
})

在上面的代码中，我们定义了一个 GET 请求，用于获取用户信息。使用 schema 选项来定义 API 文档。其中，description 和 tags 用于描述 API 的作用和标记 API 所属的组别。params 用于定义请求参数的类型和描述。response 用于定义响应的数据结构和描述。

查看 API 文档

完成了 API 文档的编写后，我们可以使用 Swagger UI 来查看 API 文档。在浏览器中访问 http://localhost:3000/documentation（假设 Fastify 的端口为 3000），即可打开 Swagger UI 页面。在页面上可以看到所有已定义的 API，以及请求和响应的数据结构。

总结

本文介绍了如何在 Fastify 框架中集成 Swagger 文档。我们首先安装了 fastify-swagger 插件，然后配置了 Swagger 和 API 文档。最后，我们使用 Swagger UI 来查看 API 文档。希望这篇文章能够帮助你更好地理解 Fastify 和 Swagger 的使用。

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