Hapi 框架中 Swagger API 文档生成与配置-JavaScript中文网-JavaScript教程资源分享门户

前言

在开发 Web 应用时，API 文档是不可或缺的一部分。API 文档可以帮助开发者理解 API 的功能和使用方法，也可以帮助团队协作和提高开发效率。Swagger 是一个流行的 API 文档生成工具，可以自动生成 API 文档并提供交互式的 UI 界面。

Hapi 是一个 Node.js 的 Web 框架，它的插件系统非常强大，可以支持各种各样的插件。在 Hapi 中，我们可以使用 swagger 插件来生成 Swagger API 文档。本文将介绍如何在 Hapi 中使用 swagger 插件生成 API 文档，并对一些常用的配置进行讲解。

安装 swagger 插件

在使用 swagger 插件之前，我们需要先安装它。可以使用 npm 进行安装：

npm install hapi-swagger --save

安装完成之后，我们需要在 Hapi 中注册 swagger 插件：

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

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

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

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

在上面的代码中，我们先引入了 Hapi、Inert、Vision 和 HapiSwagger 模块，然后创建了一个 Hapi 服务器实例。接着，我们使用 async/await 语法注册了 Inert、Vision 和 HapiSwagger 插件。在注册 HapiSwagger 插件时，我们可以传入一些配置，比如 API 的标题和版本号等。最后，我们启动了服务器并打印了它的地址。

生成 API 文档

在安装并注册了 swagger 插件之后，我们就可以生成 API 文档了。我们只需要在路由的配置中添加一些元数据，比如路由的描述、参数的类型和说明等，swagger 插件就会自动将这些信息转换成 Swagger API 文档。

// javascriptcn.com 代码示例
server.route({
  method: 'GET',
  path: '/hello/{name}',
  options: {
    description: 'Say hello to someone',
    tags: ['api'],
    validate: {
      params: Joi.object({
        name: Joi.string().required(),
      }),
    },
    handler: (request, h) => {
      return `Hello, ${request.params.name}!`;
    },
  },
});

在上面的代码中，我们定义了一个 GET 请求的路由，它的路径是 /hello/{name}，其中 {name} 是一个参数。在路由的 options 中，我们指定了路由的描述、标签、参数的类型和说明等。其中，validate 字段使用了 Joi 模块来进行参数校验。最后，我们定义了一个处理函数，它会返回一句问候语。

启动服务器后，可以在浏览器中访问 http://localhost:3000/documentation，就可以看到自动生成的 API 文档了。

配置 Swagger 插件

除了上面介绍的基本配置之外，swagger 插件还提供了很多其他的配置选项。下面我们来介绍一些常用的配置。

接口前缀

有时候我们可能需要为 API 添加一个前缀，比如 /api，可以使用 routePrefix 选项来配置：

// javascriptcn.com 代码示例
{
  plugin: HapiSwagger,
  options: {
    routePrefix: '/api/documentation',
    info: {
      title: 'My API',
      version: '1.0.0',
    },
  },
},

上面的代码中，我们将路由的前缀设置为 /api/documentation。

文档格式

swagger 插件支持多种文档格式，比如 JSON、YAML 等。可以使用 documentationPage 选项来指定文档的格式和文件名：

// javascriptcn.com 代码示例
{
  plugin: HapiSwagger,
  options: {
    documentationPage: {
      format: 'yaml',
      filename: 'swagger.yaml',
    },
    info: {
      title: 'My API',
      version: '1.0.0',
    },
  },
},

上面的代码中，我们将文档的格式设置为 YAML，并将文件名设置为 swagger.yaml。

安全认证

在实际开发中，我们可能需要对 API 进行安全认证。swagger 插件支持多种安全认证方式，比如 Basic 认证、OAuth2 等。可以使用 securityDefinitions 选项来配置安全认证方式：

// javascriptcn.com 代码示例
{
  plugin: HapiSwagger,
  options: {
    securityDefinitions: {
      basic: {
        type: 'basic',
        description: 'Basic authentication',
      },
      apiKey: {
        type: 'apiKey',
        name: 'api_key',
        in: 'header',
        description: 'API key authentication',
      },
      oauth2: {
        type: 'oauth2',
        authorizationUrl: 'https://example.com/oauth/authorize',
        tokenUrl: 'https://example.com/oauth/token',
        flow: 'implicit',
        scopes: {
          read: 'Read access',
          write: 'Write access',
        },
      },
    },
    info: {
      title: 'My API',
      version: '1.0.0',
    },
  },
},

上面的代码中，我们定义了三种安全认证方式：Basic 认证、API Key 认证和 OAuth2 认证。在路由的 options 中，我们可以使用 security 字段来指定需要使用哪种安全认证方式：

// javascriptcn.com 代码示例
server.route({
  method: 'GET',
  path: '/hello/{name}',
  options: {
    description: 'Say hello to someone',
    tags: ['api'],
    auth: {
      mode: 'required',
      strategies: ['basic'],
    },
    validate: {
      params: Joi.object({
        name: Joi.string().required(),
      }),
    },
    handler: (request, h) => {
      return `Hello, ${request.params.name}!`;
    },
  },
});

上面的代码中，我们将路由的 auth 字段设置为 required，并指定了使用 Basic 认证。

总结

本文介绍了在 Hapi 框架中使用 swagger 插件生成 API 文档的方法，并讲解了一些常用的配置选项。通过使用 swagger 插件，我们可以快速、方便地生成 API 文档，并提高开发效率。当然，在实际开发中，我们还需要根据具体的需求对 swagger 插件进行更加细致的配置，以满足项目的需求。

来源：JavaScript中文网，转载请注明来源 https://www.javascriptcn.com/post/65080c4095b1f8cacd335eba