Fastify 如何使用 Swagger 生成 API 文档-JavaScript中文网-JavaScript教程资源分享门户

在现代的 Web 应用开发中，API 文档的编写已经成为了一项必不可少的工作。但是编写大量的 API 文档不仅费时费力，而且容易出现疏漏。为了提高开发者的效率，创建一种可以自动生成 API 文档的方法就显得尤为重要。本文将重点介绍如何使用 Fastify 和 Swagger 生成 API 文档。

Fastify 框架简介

Fastify 是一个高度优化的 Web 框架，具有出色的速度和低开销。它的设计重点在于提供快速、低延迟的 Web 服务，并且在每个请求中使用最少的资源（内存或 CPU）。这使得它特别适合高流量的应用程序和微服务。

Swagger 简介

Swagger 是一个流行的开放源代码框架，用于构建和测试 API。它由智能移动和 Apigee 所共同创立。有了 Swagger，开发者们可以从 API 的开发过程中抽象出 API 的模式，并使用 Swagger 定义语言（Swagger Specification Language）来描述 API 的输入、输出以及操作。

Fastify 结合 Swagger 自动生成 API 文档

在开发 Fastify 应用程序时，您不需要使用第三方工具来生成 API 文档。Fastify 已经内置了一个插件，您可以直接使用来自动生成 API 文档。这个插件叫做 fastify-swagger。

安装 fastify-swagger

安装 fastify-swagger 插件的方法很简单：只需将其作为依赖项在您的项目中进行安装即可。请使用以下命令进行安装：

npm install --save fastify-swagger

如何在 Fastify 中使用 fastify-swagger 插件

在安装 fastify-swagger 插件后，将其连接到 Fastify 的实例中。第一步是创建一个必要的 Swagger 文件。

例如：

const fastifySwagger = require('fastify-swagger');
const path = require('path');

const options = {
  routePrefix: '/documentation',
  swagger: {
    info: {
      title: 'Fastify API',
      description: 'Testing the Fastify swagger API',
      version: '1.0.0',
    },
    externalDocs: {
      url: 'https://swagger.io',
      description: 'Find more info here',
    },
    host: 'localhost',
    schemes: ['http'],
    consumes: ['application/json'],
    produces: ['application/json'],
  },
  exposeRoute: true,
  swaggerUiConfig: {
    // 隐藏 Swagger UI 上的“Explore”选项卡
    explorer: false,
  },
};

module.exports = async function (fastify, opts) {
  fastify.register(fastifySwagger, options);

  fastify.get('/', function (request, reply) {
    reply.send({ hello: 'world' });
  });
};

这个文件定义了几个对象，其中包括：

routePrefix：用于定义路由前缀。在 Fastify 中，必须将 fastify-swagger 构建到不同的路由中，而不是默认路径“/”。
swagger：用于定义 Swagger 文件的元数据。其中包括 API 的标题、版本等信息。
exposeRoute：用于公开 API 文档的路由。这个参数默认为 true，这意味着您可以直接从浏览器中访问 Swagger API 文档。
swaggerUiConfig：用于配置 Swagger UI。这里的配置选项用于隐藏默认网页上的一些选项卡（例如“Explore”）。

最后，将 fastify-swagger 插件注册到 Fastify 的实例中。

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

fastify.register(fastifySwagger, options);

现在，您的 Fastify 应用程序可以自动生成 API 文档。如果您访问 /documentation 路径，您将看到如下所示的 Swagger UI 界面：

生成响应式 API 文档

随着移动互联网的普及，响应式设计（responsive design）已经成为 Web 应用的必不可少的部分。在 fastify-swagger 中，您可以指定 Swagger 文件的元数据，以使其在移动设备上快速响应、易于使用。

const options = {
  routePrefix: '/documentation',
  swagger: {
    info: {
      title: 'Fastify API',
      description: 'Testing the Fastify swagger API',
      version: '1.0.0',
    },
    externalDocs: {
      url: 'https://swagger.io',
      description: 'Find more info here',
    },
    host: 'localhost',
    schemes: ['http'],
    consumes: ['application/json'],
    produces: ['application/json'],
  },
  exposeRoute: true,
  swaggerUiConfig: {
    // 隐藏 Swagger UI 上的“Explore”选项卡
    explorer: false,

    // Make the Swagger UI fully responsive
    // 完全响应式的 Swagger UI
    responsive: true,
  },
};

生成多种格式的 API 文档

默认情况下，fastify-swagger 会将 API 文档生成为 JSON 和 YAML 两种格式。但是，您可以配置 fastify-swagger 来生成其他格式，例如 HTML 或 MarkDown。

下面是一份配置，该配置指定 fastify-swagger 将 Swagger 文件生成为 MarkDown 格式：

const options = {
  routePrefix: '/documentation',
  swagger: {
    info: {
      title: 'Fastify API',
      description: 'Testing the Fastify swagger API',
      version: '1.0.0',
    },
    externalDocs: {
      url: 'https://swagger.io',
      description: 'Find more info here',
    },
    host: 'localhost',
    schemes: ['http'],
    consumes: ['application/json'],
    produces: ['application/json'],
  },
  exposeRoute: true,
  swaggerUiConfig: {
    explorer: true,
    swaggerOptions: {
      syntaxHighlight: {
        enabled: true,
      },
      plugins: [
        // Fastify 集成 swagger-markdown 插件
        // https://github.com/Surnet/swagger-jsdoc/blob/master/docs/usage.md#tutorial---fastify
        require("fastify-swagger-markdown"),
      ],
    },
  },
};

总结

通过使用 fastify-swagger 插件，您可以快速、高效地为 Fastify 应用程序生成 API 文档。在本文中，我们介绍了如何安装和配置 fastify-swagger，以及如何将 Swagger 文件设置为响应式和多种格式。对于任何需要频繁更新和维护 API 文档的开发者来说，这种方法都是一项非常有用的工具和技术。

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