在 Hapi 中使用 Swagger UI 进行 API 接口文档管理的实践教程

本文将介绍如何在 Hapi 框架中使用 Swagger UI 进行 API 接口文档管理。Swagger 是一种基于 OpenAPI 规范的 API 文档管理工具，可以帮助开发者更好地管理和调试 API 接口。在使用 Hapi 框架开发 API 时，Swagger UI 可以方便地集成到项目中，提供可视化的接口文档和测试工具。

前提条件

在开始本教程前，需要确保已经安装了以下软件：

• Node.js
• Hapi 框架
• Swagger UI

本教程将以 Hapi 20.1.4 版本和 Swagger UI 3.32.1 版本为例进行演示。

步骤一：安装 Swagger UI

首先需要安装 Swagger UI。可以通过 npm 包管理器进行安装：

npm install swagger-ui-express

安装完成后，在项目的入口文件中引入 Swagger UI：

const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

其中，swaggerDocument 是一个 JSON 文件，用于描述 API 接口的信息。下一步将介绍如何生成这个文件。

步骤二：编写 Swagger 文档

Swagger 文档是一个 JSON 文件，用于描述 API 接口的信息。可以通过编写 JSON 文件或使用 Swagger Editor 工具生成。

以下是一个简单的 Swagger 文档示例，用于描述一个 GET 请求：

// javascriptcn.com 代码示例
{
  "swagger": "2.0",
  "info": {
    "title": "My API",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "summary": "Get a list of users",
        "description": "Returns a list of all users",
        "responses": {
          "200": {
            "description": "A list of users",
            "schema": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "integer"
                  },
                  "name": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

在实际开发中，可以使用 Swagger 的注解来生成 Swagger 文档。例如，在 Hapi 中可以使用 hapi-swagger 插件，将路由注解转换为 Swagger 文档。

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

const init = async () => {

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

    const swaggerOptions = {
        info: {
            title: 'Test API Documentation',
            version: Pack.version,
        },
    };

    await server.register([
        Inert,
        Vision,
        {
            plugin: HapiSwagger,
            options: swaggerOptions
        }
    ]);

    server.route({
        method: 'GET',
        path: '/users',
        config: {
            tags: ['api'],
            description: 'Get a list of users',
            handler: async (request, h) => {
                return [
                    {id: 1, name: 'John'},
                    {id: 2, name: 'Jane'}
                ];
            },
            response: {
                schema: {
                    type: 'array',
                    items: {
                        type: 'object',
                        properties: {
                            id: {type: 'integer'},
                            name: {type: 'string'}
                        }
                    }
                }
            }
        }
    });

    await server.start();
    console.log('Server running on %s', server.info.uri);
};

process.on('unhandledRejection', (err) => {

    console.log(err);
    process.exit(1);
});

init();

在上面的示例中，使用了 hapi-swagger 插件将路由注解转换为 Swagger 文档。通过访问 /documentation 路径，可以查看生成的 Swagger 文档。

步骤三：使用 Swagger UI

当 Swagger 文档编写完成后，可以使用 Swagger UI 进行可视化展示。在 Hapi 项目中，可以通过引入 swagger-ui-express 包并将 Swagger 文档传递给 setup 方法来实现。

const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

上述代码将 Swagger UI 映射到 /api-docs 路径下。访问该路径，即可查看可视化的 Swagger 文档和测试工具。

总结

本文介绍了在 Hapi 中使用 Swagger UI 进行 API 接口文档管理的实践教程。首先需要安装 Swagger UI，并编写 Swagger 文档。然后，将 Swagger UI 集成到 Hapi 项目中，即可实现可视化的接口文档和测试工具。通过使用 Swagger UI，可以更好地管理和调试 API 接口，提高开发效率。

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