使用 hapi-swagger-ui 生成美观的 API 文档-JavaScript中文网-JavaScript教程资源分享门户

在现代的 Web 应用中，前后端分离已经成为了一种常见的架构模式。对于后端开发来说，API 文档对于前端和其他协作开发者都是非常重要的。而 hapi-swagger-ui 这个工具，可以帮助你轻松地生成美观且易于使用的 API 文档。

什么是 hapi-swagger-ui？

hapi-swagger-ui 是一个基于 hapi 框架的插件，它可以自动地生成美观的 API 文档，并通过 Swagger UI 来展示这些文档。它支持 OpenAPI 规范，支持在文档中显示参数、请求、响应和生成测试代码等功能。

如何使用 hapi-swagger-ui？

首先，你需要在你的项目中安装 hapi 和 hapi-swagger-ui：

npm install hapi hapi-swagger hapi-swagger-ui --save-dev

然后在你的 hapi 服务中引入 hapi-swagger-ui 插件，并配置接口文档的路由：

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

const swaggerOptions = {
  info: {
    title: 'API 文档',
    version: Pack.version,
  },
};

const server = new Hapi.Server();

server.connection({
  host: 'localhost',
  port: 3000,
});

server.register([Inert, Vision, {
  register: HapiSwagger,
  options: swaggerOptions,
}], (err) => {
  if (err) {
    console.error(err);
  }
});

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

接下来，在你的路由定义中，可以添加 Swagger 相关的参数和描述信息，例如：

// javascriptcn.com 代码示例
server.route({
  method: 'GET',
  path: '/api/users',
  config: {
    tags: ['api'],
    description: '获取用户列表',
    notes: '通过分页参数来获取用户列表',
    validate: {
      query: {
        page: Joi.number().integer().min(1).default(1),
        pageSize: Joi.number().integer().min(1).max(100).default(20),
      },
    },
  },
  handler: (request, reply) => {
    // 实现获取用户列表的逻辑
  },
});

这样，在 Swagger UI 中，就可以展示出接口的详细信息和参数定义，让其他开发者能够更加方便地使用你的 API。

hapi-swagger-ui 的配置选项

hapi-swagger-ui 支持一些配置选项，可以通过 HapiSwagger 的参数来指定。例如：

// javascriptcn.com 代码示例
const swaggerOptions = {
  info: {
    title: 'API 文档',
    version: Pack.version,
  },
  schemes: ['https'],
  host: 'api.example.com',
  basePath: '/v1',
  routePrefix: '/api-docs',
  documentationPath: '/docs',
  jsonPath: '/swagger.json',
  sortEndpoints: 'path',
  sortTags: 'name',
  tags: [
    { name: 'users', description: '用户相关接口' },
    { name: 'orders', description: '订单相关接口' },
  ],
};

其中，常用的配置选项包括：

info：API 文档的基本信息，包括标题、版本号等；
schemes：支持的协议，可以是 http、https 等；
host：API 的主机名；
basePath：API 的基础路径，一般是版本号；
tag：API 接口的分类，可以在 Swagger UI 中按照分类进行选择。

总结

使用 hapi-swagger-ui，可以帮助开发者轻松地生成美观易用的 API 文档，提高 API 的可维护性和可用性。在使用 hapi-swagger-ui 前，需要熟悉 OpenAPI 规范和 hapi 框架，以便正确地配置相关参数。

完整代码示例：https://github.com/hapijs/hapi-swagger#hapi-swagger-example

参考文档：https://github.com/hapijs/hapi-swagger/blob/master/examples/basic.js

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