我应该如何将 Swagger 与 Hapi 一起使用？

Posted 2023-03-08

【中文标题】我应该如何将 Swagger 与 Hapi 一起使用？

【英文标题】：How should I use Swagger with Hapi?

【发布时间】：2016-06-29 15:33:02

【问题描述】：

我有一个正常工作的普通 Hapi 应用程序，我计划迁移到 Swagger。我使用官方说明安装了swagger-node，并在执行'swagger project create'时选择了Hapi。但是，我现在很困惑，因为似乎有几个用于集成 swagger-node 和 hapi 的库：

hapi-swagger：最受欢迎的一个 hapi-swaggered: 有点受欢迎 swagger-hapi：不受欢迎且不那么活跃，但被官方 Swagger Node.js 库（即swagger-node）用作 Hapi 项目的默认设置

虽然 swagger-hapi 是“官方”方法，但我试图找到有关如何在 Hapi 路由上进行各种配置的信息（例如授权、范围等）。似乎这些方法根本不同，swagger-hapi 将 Swagger 定义作为输入并自动生成路由，而 hapi-swagger 和 hapi-swaggered 似乎彼此具有相似的方法，仅从普通的旧 Hapi 生成 Swagger API 文档路线定义。

考虑到贡献者的数量和下载的数量，hapi-swagger 似乎是要走的路，但我不确定如何进行。是否有设置 Hapi 的“官方”Swagger 方式，如果有，我该如何设置身份验证（最好使用hapi-auth-jwt2，或其他类似的 JWT 解决方案）和授权？

编辑：我还发现了swaggerize-hapi，它似乎由 PayPal 的开源 kraken.js 团队维护，这表明它可能有某种企业支持（总是一件好事）。 swaggerize-hapi 似乎与 hapi-swagger 非常相似，尽管后者似乎提供了更多开箱即用的功能（主要是 Swagger 编辑器）。

【问题讨论】：

我使用 hapi-swagger 来记录路线。您是否希望使用生成的 JSON 文件来做更多的事情？

我想要一个插件，可以根据 Swagger 定义动态生成 Hapi 路由（例如 swagger-node/swagger-hapi 或 swaggerize-hapi）。我真的没有看到首先编写 Hapi 路由然后从这些路由生成 Swagger 定义和/或文档的意义。

你解决过这个问题吗？

@k0pernikus 我决定使用 swaggerize-hapi，因为它允许我从 OpenAPI 定义文件即时生成 Hapi 路由。我遇到了 swaggerize-routes 的一些问题，这是负责生成路由的依赖项，但我至少找到了临时解决方案。 github.com/krakenjs/swaggerize-routes/compare/… 完成我正在进行的项目后，我将在 Github 上发布一个示例项目。

【参考方案1】：

编辑：第 3 点。从您的问题出发，了解 swagger-hapi 的实际作用非常重要。它不直接提供 swagger-ui html。它不是有意的，但它使整个大摇大摆的想法成为可能（第 1 点和第 2 点中的其他项目实际上有点颠倒了）。请看下文。

事实证明，当您使用 swagger-node 和 swagger-hapi 时，除了直接使用 swagger-ui 之外，您不需要所有其余的软件包（无论如何其他人都使用它 - 它们是将其包装在它们的依赖项中）

我想在这个 hapi/swagger 谜题中分享我目前的理解，希望我花费的这 8 个小时也能帮助到其他人。

像 hapi-swaggered、hapi-swaggered-ui 和 hapi-swagger 这样的库 - 它们都遵循相同的方法 - 可以这样描述：

You document your API while you are defining your routes

它们有点远离swagger-node 的主要思想和使用swagger-cli 创建的样板hello_world 项目，你提到你使用了。

虽然swagger-node 和swagger-hapi（注意它与hapi-swagger 不同）在说：

You define all your API documentation and routes **in a single centralized place - swagger.yaml**

然后您只需专注于编写控制器逻辑。 swagger-cli 提供的样板项目已经通过 /swagger 端点将这个集中的地方 swagger.yaml 公开为 json。

现在，因为上述所有软件包都用于显示 UI 的 swagger-ui 项目只是一堆静态 html - 为了使用它，您有两个选择：

1) 在您的应用内自行托管此静态 html

2) 将其托管在单独的 Web 应用程序上，甚至直接从文件系统加载 index.html。

在这两种情况下，您只需要使用您的 swagger json 提供 swagger-ui - 如上所述，/swagger 端点已经公开了它。

如果您选择选项 2)，唯一需要注意的是，您需要为该端点启用 cors，这恰好非常容易。只需更改您的 default.yaml，也可以使用 cors 风笛。请参阅此thread 了解如何执行此操作。

正如@Kitanotori 上面所说，我也没有看到以编程方式记录代码的意义。只在一个地方描述所有内容并让代码和文档引擎都能理解它的想法很棒。

【讨论】：

我理解在 swagger.json 中记录所有内容的想法，但是随着 api 频繁更改并且如果文档没有更新（在大多数情况下），它会造成合同中断，而人们不会然后按照文档进行操作。我想自动生成文档，以便它们始终更新。

【参考方案2】：

我们使用过 Inert、Vision、hapi-swagger。

server.ts

import * as Inert from '@hapi/inert';
import * as Vision from '@hapi/vision';
import Swagger from './plugins/swagger';
...
...
// hapi server setup
...
const plugins: any[] = [Inert, Vision, Swagger];
await server.register(plugins);
...
// other setup

./plugins/swagger

import * as HapiSwagger from 'hapi-swagger';

import * as Package from '../../package.json';

const swaggerOptions: HapiSwagger.RegisterOptions = 
  info: 
    title: 'Some title',
    version: Package.version
  
;

export default 
  plugin: HapiSwagger,
  options: swaggerOptions
;

【参考方案3】：

我们正在使用 Inert、Vision 和 hapi-swagger 来构建和托管 swagger 文档。 我们完全按照这个顺序加载这些插件，不配置 Inert 或 Vision，只在 hapi-swagger 配置中设置标题等基本属性。