如何在 Hapi 中使用 Swagger 进行 API 文档自动生成-JavaScript中文网-JavaScript教程资源分享门户

前言

在开发 Web 应用程序时，API 文档是一个非常重要的部分。API 文档可以帮助开发人员理解和使用我们创建的 API。Swagger 是一个流行的开源框架，它提供了一种快速、易于使用的方式来创建和管理 API 文档。在本文中，我们将探讨如何在 Hapi 中使用 Swagger 进行 API 文档自动生成。

Hapi 是什么？

Hapi 是一个流程模型的 Node.js Web 框架，它的优点在于易于使用和插件化。Hapi 的插件性允许你添加需要的功能，例如路由管理、缓存、日志和验证等等。

Swagger 是什么？

Swagger 是一个开源的规范和工具集，使得 RESTful Web 服务更容易进行发现、联合编程、版本控制和还原。Swagger 遵循 OpenAPI 规范，助力于在可互操作的代码和 API 类型的自动生成的基础上构建更好的 API。

在 Hapi 中使用 Swagger

Swagger 已经支持了目前主流的 Web 后端框架，我们来看一下在 Hapi 中如何使用 Swagger 进行 API 文档自动生成。

安装 Hapi 和 Swagger

首先，我们需要安装 Hapi 和 Swagger。在安装 Swagger 之前我们要先初始化一个 Hapi 项目，打开命令行并输入以下命令：

$ npm init
$ npm install hapi --save

接下来，通过以下命令来安装 Swagger 依赖包：

$ npm install hapi-swagger --save

配置 Swagger

在 Hapi 项目的入口文件中，我们需要加载至少以下两个插件：

// javascriptcn.com 代码示例
const Hapi = require('hapi');
const Inert = require('inert');
const Vision = require('vision');
const HapiSwagger = require('hapi-swagger');
const Pack = require('./package');
const Path = require('path');
const Joi = require('@hapi/joi');

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

const init = async() => {

    await server.register([
        Inert,
        Vision,
        {
            plugin: HapiSwagger,
            options: {
                schemes: ['http'],
                host: 'localhost:3000',
                info: {
                    title: 'Example API Documentation',
                    version: Pack.version,
                },
                securityDefinitions: {
                    JWT: {
                        type: 'apiKey',
                        name: 'Authorization',
                        in: 'header',
                        description: 'Bearer {token}',
                    },
                },
                security: [{ JWT: [] }],
            }
        }
    ]);

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

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

process.on('unhandledRejection', (err) => {
    console.log(err);
    process.exit(1);
});

init();

在这个示例中，我们定义了一个最基本的 Hapi 服务器。在 register 方法中，我们加载了 Inert 和 Vision 插件，这两个插件是必须的。 Vision 插件使用来为 Hapi 服务器提供模板引擎的支持。我们还加载了 hapi-swagger 插件，这个插件提供了 Swagger 的支持。初始化完之后我们创建了一个路由对象，这个路由仅仅返回了一个静态的字符串”Hello, world!” ，同时该路由打上了 tag。

在 options 选项的部分，我们可以看到一些 Swagger 的配置信息。如下所示的是配置信息的含义：

schemes：HTTP 协议的可选方案；
host：API 的服务域名和端口；
info：API 的摘要信息；
securityDefinitions：认证的定义；
security：API 需要验证的安全类型，例如 JWT。

为路由添加 Swagger 配置

之前我们仅仅是定义了一个仅有 tag 的路由，这里我们来看一下如何为路由提供 Swagger 配置，并添加对应的 tag、description、summary 和 response 的内容。

// javascriptcn.com 代码示例
server.route({
    path: '/users/{id}',
    method: 'GET',
    handler: (request, h) => {
        const { id } = request.params;

        return { userId: request.params.id };
    },
    options: {
        tags: ['api'],
        validate: {
            params: Joi.object({
                id: Joi.number().integer().min(0),
            })
        },
        description: "Get user by ID",
        notes: "Returns a user object",
        summary: "Get user by ID",
        response: {
            schema: Joi.object({
                userId: Joi.number().required(),
            }),
            status: {
                200: 'OK',
                404: 'Not Found'
            }
        },
    },
});

在这个示例中，我们为路由添加了一个参数 id。这个参数必须是一个数字，我们使用了 Joi 的 validate 方法来验证它。在 options 中，我们定义了 tags、description、notes、summary 和 response。这些信息元素被用来生成 Swagger 文档。

自动生成 API 文档

在启动 Hapi 服务器后，我们访问 http://localhost:3000/documentation，我们可以看到自动生成的 API 文档，如下所示。

恭喜你！你已经实现了通过 Swagger 自动生成 API 文档的功能。

总结

在本文中，我们介绍了 Swagger 和 Hapi 的基础知识，并展示了如何在 Hapi 中使用 Swagger 进行 API 文档自动生成。本文的目的是帮助 Hapi 开发人员更好地理解和使用 Swagger ，根据这些方法不仅可以让我们更快完成一个项目，也可以让我们能够在开发过程中更好地管理我们的 API 文档。

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