Swagger 是一种用于描述和控制 RESTful Web 服务的工具。而 Swagger UI 则是 Swagger 的一个开源项目，它用于将 Swagger API 文档渲染为交互式 API 文档页面。通过 Swagger UI，你可以很容易地查看和测试你的 API，而不需要编写任何代码。在本文中，我们将讨论如何在 Hapi 框架中使用 Swagger UI，来更好地管理和发布你的 Web API。
Step 1: 安装 Swagger UI
首先，你需要安装 Swagger UI 的 npm 包，可以使用以下命令：
npm install swagger-ui-dist --save
Step 2: 配置 Swagger UI
在你的 Hapi 项目中，你需要设置一个路由来提供 Swagger UI。在这个路由中，你需要指定 Swagger API 文件所在的 URL，以及渲染 Swagger UI 所需的文件。以下是一个示例路由的代码：
// javascriptcn.com 代码示例
const Hapi = require('hapi')
const Inert = require('@hapi/inert')
const Vision = require('@hapi/vision')
const Pack = require('./package')
const HapiSwagger = require('hapi-swagger')
// 创建 server
const server = new Hapi.Server({
host: 'localhost',
port: 3000
})
// 注册插件
await server.register([
Inert,
Vision,
{
plugin: HapiSwagger,
options: {
info: {
title: 'API Documentation',
version: Pack.version,
},
swaggerUI: true,
documentationPage: false,
documentationPath: '/docs',
swaggerUIPath: '/docs/swaggerui/',
swaggerUIConfig: {
url: '/docs/api-docs.json',
},
},
},
])
// 注册路由
server.route({
method: 'GET',
path: '/docs/swaggerui/{param*}',
handler: {
directory: {
path: './node_modules/swagger-ui-dist/'
}
},
options: {
description: 'Swagger ui',
notes: 'Swagger 开源框架用来自动生成、描述、测试和文档化 RESTful 风格的 Web 服务。',
tags: ['api', 'swagger'],
plugins: {
'hapi-swagger': {
responses: {
200: {
description: '成功'
}
}
}
}
}
})其中，Inert 和 Vision 是 Hapi 插件，在这里我们使用它们来提供静态文件和模板引擎的功能。HapiSwagger 是用于将 Swagger API 定义转换为 Swagger UI 页面的插件。
在 options 中，我们可以配置一些选项来指定 Swagger UI 的相关设置。在本例中，我们禁用了默认的 Swagger API 文档页面 documentationPage，指定了 Swagger API 文档的路径 documentationPath，以及 Swagger UI 渲染的路径 swaggerUIPath。swaggerUIConfig 是一个用于配置 Swagger UI 的对象，其中我们指定了 API 文档文件的 URL。
最后，在路由中，我们设置了一个 GET 方法，用于提供 Swagger UI 的静态文件。通过 directory 插件，我们将请求映射到 ./node_modules/swagger-ui-dist/ 目录下，以提供 Swagger UI 所需的静态文件。
Step 3: 生成 Swagger API 文档
最后，你需要在你的 Hapi 服务中添加 Swagger API 文档。HapiSwagger 插件会将其转换为 Swagger UI 所需的格式。以下是一个示例文档的代码：
// javascriptcn.com 代码示例
const Joi = require('joi')
const Pack = require('./package')
module.exports = [
{
method: 'GET',
path: '/api/hello',
options: {
description: 'Get hello message.',
notes: 'Returns a hello message.',
tags: ['api'],
plugins: {
'hapi-swagger': {
responses: {
200: {
description: 'Success',
schema: Joi.object({
message: Joi.string().description('Hello message.'),
})
},
404: {
description: 'Not found',
}
},
},
},
},
handler: (request, h) => {
return {
message: 'Hello, world!',
}
},
},
{
method: 'GET',
path: '/docs/api-docs.json',
options: {
description: 'Swagger API definition',
notes: 'Returns a Swagger API definition file in JSON format.',
tags: ['api', 'swagger'],
plugins: {
'hapi-swagger': {
produces: ['application/json'],
consumes: ['application/json'],
},
},
},
handler: (request, h) => {
return h.view('./views/api-docs.json', {
title: Pack.name + ' API Documentation',
version: Pack.version,
server: request.server.info.uri,
routes: request.server.table().filter((r) => r.settings.plugins['hapi-swagger']),
}, {
layout: false,
})
},
},
]在 options 中，我们设置了与路由相应的 Swagger API 描述信息。Joi 是一个用于校验数据的库，它将帮助我们生成 Swagger API 的请求和响应体的 schema。在其中，我们可以使用 description 和 notes 来描述该 API 的作用以及使用方法。tags 用于指定该 API 的分类，方便查找和管理。
在 plugins 中，我们可以设置一些关于该 API 的其他信息。其中，hapi-swagger 插件提供了 responses 选项，用于定义该 API 可能会产生的响应内容。当你向浏览器请求 /docs/api-docs.json 路径时，该 API 将返回一份 Swagger API 文档，该文档将被 HapiSwagger 插件转换为 Swagger UI 所需的格式。
在 handler 中，我们定义了该 API 的处理逻辑。在这个例子中，它非常简单，只是返回一个 JSON 对象。在 /docs/api-docs.json 路径下，我们使用了 h.view 方法，它会将一个视图渲染为一个字符串。我们将自定义的数据传递给该视图，生成一个 Swagger API 文档，并返回给浏览器。
总结
现在，你已经掌握了在 Hapi 框架中使用 Swagger UI 的实现方法。Swagger UI 可以帮助你更好地管理你的 Web API，提高生产力和可维护性。在本文中，我们介绍了如何安装和配置 Swagger UI，并生成 Swagger API 文档。在实际的项目中，你可以根据需求，选择自己喜欢的方式来使用 Swagger UI。
来源：JavaScript中文网 ，转载请注明来源 本文地址：https://www.javascriptcn.com/post/6544c8637d4982a6ebe9cf80