Hapi.js 开发：使用 hapi-swagger 自动生成 API 文档-JavaScript中文网-JavaScript教程资源分享门户

Hapi.js 是 Node.js 的一个开源框架，它可以帮助我们快速构建可扩展的 Web 应用程序。在 Hapi.js 中，我们可以使用 hapi-swagger 插件来自动生成 API 文档，这样我们就可以更加方便地管理和维护我们的 API 文档。

在本文中，我们将介绍如何使用 hapi-swagger 插件来自动生成 API 文档，并提供一些示例代码和指导意义，帮助你更好地理解和应用这个插件。

安装 hapi-swagger 插件

在开始使用 hapi-swagger 插件之前，我们需要先安装它。我们可以使用 npm 命令来安装 hapi-swagger 插件：

npm install hapi-swagger

配置 hapi-swagger 插件

安装好 hapi-swagger 插件后，我们需要在 Hapi.js 应用程序中配置它。我们可以在 Hapi.js 应用程序的启动文件中添加以下代码来配置 hapi-swagger 插件：

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

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

const init = async () => {

    await server.register([
        Inert,
        Vision,
        {
            plugin: HapiSwagger,
            options: {
                info: {
                    title: 'API 文档',
                    version: '1.0.0'
                }
            }
        }
    ]);

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

init();

在上面的代码中，我们首先引入了 Hapi.js、Inert、Vision 和 HapiSwagger 这些模块。然后，我们使用 Hapi.server() 方法创建了一个 Hapi.js 服务器，指定了端口号和主机名。

接着，我们使用 await server.register() 方法注册了 Inert、Vision 和 HapiSwagger 这三个插件。其中，Inert 和 Vision 插件是 hapi-swagger 插件的依赖项，需要一起安装和注册。

在注册 HapiSwagger 插件时，我们还可以通过 options 参数来指定一些配置选项。在上面的代码中，我们指定了 API 文档的标题和版本号。

最后，我们调用 await server.start() 方法启动服务器，并在控制台输出了服务器的地址。

自动生成 API 文档

完成了配置 hapi-swagger 插件的工作后，我们就可以开始使用它来自动生成 API 文档了。

假设我们有一个简单的 API，它包含了一个 GET 请求和一个 POST 请求：

// javascriptcn.com 代码示例
server.route({
    method: 'GET',
    path: '/hello/{name}',
    handler: (request, h) => {
        return `Hello, ${request.params.name}!`;
    }
});

server.route({
    method: 'POST',
    path: '/users',
    handler: (request, h) => {
        const user = request.payload;
        return `Created user: ${JSON.stringify(user)}`;
    },
    options: {
        validate: {
            payload: Joi.object({
                name: Joi.string().required(),
                email: Joi.string().email().required()
            })
        }
    }
});

使用 hapi-swagger 插件，我们可以在 API 中添加一些注释和元数据，来描述 API 的参数、响应和其他信息。例如，我们可以在 GET 请求的路由中添加以下注释：

// javascriptcn.com 代码示例
server.route({
    method: 'GET',
    path: '/hello/{name}',
    handler: (request, h) => {
        return `Hello, ${request.params.name}!`;
    },
    options: {
        description: 'Say hello to a user',
        notes: 'The name parameter is required',
        tags: ['api'],
        validate: {
            params: Joi.object({
                name: Joi.string().required().description('The name of the user')
            })
        },
        plugins: {
            'hapi-swagger': {
                responses: {
                    '200': {
                        description: 'Success',
                        schema: Joi.string()
                    },
                    '400': {
                        description: 'Bad Request',
                        schema: Joi.object({
                            statusCode: Joi.number().default(400),
                            error: Joi.string().default('Bad Request'),
                            message: Joi.string().default('Invalid request parameters')
                        })
                    }
                }
            }
        }
    }
});

在上面的代码中，我们在 options 参数中添加了一些注释和元数据，来描述 GET 请求的路由。其中，description、notes 和 tags 属性是 hapi-swagger 插件的标准属性，用来描述 API 的基本信息和分类。

validate 属性是 Hapi.js 的一个内置属性，用来验证请求参数。在这里，我们使用 Joi 对请求参数进行了验证，并添加了一些描述信息。

plugins 属性是 hapi-swagger 插件的一个自定义属性，用来描述 API 的响应和其他信息。在这里，我们使用 responses 属性来描述 GET 请求的响应。其中，'200' 和 '400' 是响应的状态码，description 属性是响应的描述信息，schema 属性是响应的数据结构。

类似地，我们也可以在 POST 请求的路由中添加注释和元数据：

// javascriptcn.com 代码示例
server.route({
    method: 'POST',
    path: '/users',
    handler: (request, h) => {
        const user = request.payload;
        return `Created user: ${JSON.stringify(user)}`;
    },
    options: {
        description: 'Create a new user',
        notes: 'The name and email parameters are required',
        tags: ['api'],
        validate: {
            payload: Joi.object({
                name: Joi.string().required().description('The name of the user'),
                email: Joi.string().email().required().description('The email of the user')
            })
        },
        plugins: {
            'hapi-swagger': {
                responses: {
                    '201': {
                        description: 'Created',
                        schema: Joi.object({
                            name: Joi.string().required(),
                            email: Joi.string().email().required()
                        })
                    },
                    '400': {
                        description: 'Bad Request',
                        schema: Joi.object({
                            statusCode: Joi.number().default(400),
                            error: Joi.string().default('Bad Request'),
                            message: Joi.string().default('Invalid request parameters')
                        })
                    }
                }
            }
        }
    }
});

查看 API 文档

完成了上面的工作后，我们就可以在浏览器中查看自动生成的 API 文档了。我们只需要访问以下 URL：

http://localhost:3000/documentation

在浏览器中打开这个 URL 后，就可以看到自动生成的 API 文档了。我们可以在文档中查看 API 的详细信息，包括请求和响应的参数、数据结构和描述信息等。

总结

在本文中，我们介绍了如何使用 hapi-swagger 插件来自动生成 API 文档。我们首先安装了 hapi-swagger 插件，然后在 Hapi.js 应用程序中配置了它。接着，我们使用 hapi-swagger 插件在 API 中添加了注释和元数据，来描述 API 的参数、响应和其他信息。最后，我们在浏览器中查看了自动生成的 API 文档。

使用 hapi-swagger 插件可以帮助我们更加方便地管理和维护 API 文档，提高开发效率和代码质量。如果你正在使用 Hapi.js 开发 Web 应用程序，那么 hapi-swagger 插件一定是一个不错的选择。

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