如何使用 hapi-swagger 在 Hapi 中自动生成 API 文档

前言

作为一个前端开发人员，在与后端开发人员协作时，我们经常需要进行 API 文档的编写和维护。这是一个繁琐而重要的任务，因为 API 文档可以帮助我们更好地理解后端提供的接口，并且在我们需要开发前端应用时，也可以方便我们快速地构建应用。在这方面，hapi-swagger 是一个非常好用的工具，它可以帮助我们在 Hapi 中自动生成 API 文档。在本文中，我们将详细介绍如何使用 hapi-swagger 来生成 API 文档。

Hapi-swagger 简介

Hapi-swagger 是一个用于 Hapi 的插件，它可以帮助我们在 Hapi 应用程序中自动生成 Swagger / OpenAPI 文档。Swagger / OpenAPI 是一种基于 JSON 或 YAML 格式的 API 描述规范，它可以帮助我们通过定义接口的元数据来描述我们的 API。利用 Swagger / OpenAPI，我们可以在不需要访问实际代码的情况下生成 API 文档，这非常方便，因为我们不需要手动编写 API 文档。

由于 Hapi-swagger 基于 Swagger / OpenAPI，所以我们可以利用 Swagger UI 等工具，以可视化的方式查看 API 文档。同时，Swagger / OpenAPI 规范在很多开发工具中也得到了支持，如 Postman 等。

安装 hapi-swagger

在开始使用 hapi-swagger 之前，我们需要先安装它。我们可以通过 npm 包管理器来安装它：

安装完成之后，在应用程序中引入它：

const HapiSwagger = require('hapi-swagger');

在 Hapi 中使用 hapi-swagger

下面我们来看一下如何在 Hapi 中使用 hapi-swagger。

首先，我们需要在 Hapi 应用程序中注册 hapi-swagger 插件。我们可以在 Hapi 的 server.register() 方法中进行注册。我们需要传入一些配置选项来告诉 hapi-swagger 如何生成 API 文档。

下面是一个完整的例子：

const Hapi = require('@hapi/hapi');
const HapiSwagger = require('hapi-swagger');
const Pack = require('./package');

const init = async () => {

    const server = Hapi.server({
        port: 3000,
        host: 'localhost'
    });

    const swaggerOptions = {
        info: {
            title: Pack.name,
            version: Pack.version,
        },
    };

    await server.register([
        require('inert'),
        require('vision'),
        {
            plugin: HapiSwagger,
            options: swaggerOptions
        }
    ]);

    server.route([
        {
            method: 'GET',
            path: '/hello',
            handler: (request, h) => {
                return 'Hello, world!';
            },
            options: {
                tags: ['api'],
                description: 'Say hello',
                notes: 'Returns a hello message',
            }
        }
    ]);

    await server.start();
    console.log(`Server running at: ${server.info.uri}`);
};

init();

在这个例子中，我们首先定义了一个 Hapi 服务器并指定其监听地址和端口。然后，我们定义了一个 swaggerOptions 配置对象，其中包括 API 文档的标题和版本号。接下来，我们通过 server.register() 方法来注册 hapi-swagger 插件，并传入 swaggerOptions 配置选项。在上述代码中，我们还定义了一个简单的路由 /hello，并通过在路由配置选项中设置 tags、description 和 notes 参数来告诉 hapi-swagger 插件如何生成 API 文档。

最后，我们使用 server.start() 方法来启动应用程序。如果启动成功，我们将看到控制台输出应用程序的监听地址和端口。

默认情况下，hapi-swagger 将使用 Joi 模块的描述对象来解析我们的路由配置选项，以生成 API 文档。如果我们要使用其他描述对象，可以在配置选项中设置 validatorUrl 属性来指定验证器 URL。

使用 hapi-swagger 生成 API 文档

现在，我们已经在 Hapi 中成功使用了 hapi-swagger 插件。接下来，我们将进一步介绍如何使用它来生成 API 文档。

我们可以通过访问 /documentation 路由来查看由 hapi-swagger 生成的 API 文档。例如，我们在 Hapi 应用程序中启动了服务并监听 3000 端口，那么我们可以在浏览器中输入 http://localhost:3000/documentation，就可以看到自动生成的 API 文档。

在下面的屏幕截图中，我们可以看到 hapi-swagger 生成的 API 文档样例。我们可以看到 API 文档是由多个部分组成的，包括概览、标签、路径和定义等。我们可以通过 Swagger UI 工具来查看这些文档，并与之交互。

在创建路由时，我们可以使用路由配置选项来指定每个路由的元数据。这些元数据可以帮助 hapi-swagger 自动生成 API 文档，包括标签、路径、操作、参数、请求体和响应体等。下面是一个完整的路由配置选项样例：

{
  method: 'POST',
  path: '/api/items',
  handler: (request, h) => {
    return { message: 'Item created!' };
  },
  options: {
    tags: ['api'],
    description: 'Create a new item',
    notes: 'Create a new item in the system',
    plugins: {
      'hapi-swagger': {
        responses: {
          '201': {
            description: 'Item created successfully',
            schema: Joi.object({
              message: Joi.string().required()
            })
          },
          '400': {
            description: 'Invalid input',
            schema: Joi.object({
              statusCode: Joi.number().required().example(400),
              message: Joi.string().required().example('Invalid input')
            })
          }
        }
      }
    },
    validate: {
      payload: Joi.object({
        name: Joi.string().required().description('Item name'),
        price: Joi.number().required().description('Item price')
      })
    },
    response: {
      status: {
        // HTTP response status for successful requests
        201: Joi.object({
          message: Joi.string().required()
        })
      }
    },
  }
}

在配置选项中我们可以指定多个参数来告诉 hapi-swagger 插件如何生成 API 文档。下面是一些最常用的参数：

  • tags - 标签数组，将其用于函数的路由标记以在 Swagger UI 中组织和过滤方法。
  • description - 描述路由的简短描述。
  • notes - 提供有关路由的长描述和其他说明。
  • validate - 指定 Joi 模板对象，用于验证和描述 payload、params、query 和 headers 实例数据模型。
  • response - 关键描述服务可以响应客户端请求的期望输出。
  • plugins - 为 hapi-swagger 定义一些特殊的规则，以控制文档生成的结果。

使用 hapi-swagger 生成的 API 文档在 Swagger UI 中呈现得非常清晰，并且可以与 Postman 等工具相集成。这使得 API 文档可以帮助我们更好地理解后端为我们提供的所有可用接口。同时，在前端开发过程中，我们可以使用 API 文档作为参考，更快地构建应用程序。

总结

在本文中，我们介绍了如何在 Hapi 中使用 hapi-swagger 插件来自动生成 API 文档。我们已经看到，hapi-swagger 是一个非常好用且易于使用的插件，它可以帮助我们更好地管理和维护我们的 API 文档。使用 hapi-swagger，我们可以大大提高前后端协作的效率，同时减少繁琐的手动编写 API 文档的过程。因此，在我们的前端开发过程中，使用 hapi-swagger 是非常必要的。

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

阅读全文

精选内容

相关推荐

    暂无