在 Fastify 服务中使用 Swagger UI-JavaScript中文网-JavaScript教程资源分享门户

介绍

Swagger UI 是一个流行的 API 文档生成工具，它可以自动生成 API 文档并提供一个漂亮的交互式用户界面，便于用户通过浏览器直观地了解和测试 API。

Fastify 是一个快速、低开销、高效的 Node.js Web 框架。本文将介绍如何在 Fastify 服务中集成 Swagger UI，以便于用户更加直观地了解和使用 API。

安装依赖

首先，需要安装以下依赖：

fastify-swagger: 将 Fastify API 转化为 Swagger 规范，并提供 Swagger UI 界面。
fastify-autoload: 将 routes/ 目录下的所有文件导入到 Fastify 实例中。

可以使用以下命令安装：

npm install fastify-swagger fastify-autoload

添加 Swagger UI 插件

在 Fastify 应用程序中，添加 Swagger UI 插件以生成 API 文档。以下是一个示例 Fastify 应用程序：

-- -------------------- ---- -------
----- ------- - --------------------
  ------- ----
--

-------------------------------------------- -
  ------------ -----------------
  -------- -
    ----- -
      ------ ---- ---------------
      ------------ ---- ---------------
      -------- -------
    --
    ----- -----------------
    -------- ---------
    --------- ---------------------
    --------- ---------------------
  --
  ------------ ----
--

--------------------------------------------- -
  ---- -------------------- ---------
--

----- ----- - ----- -- -- -
  --- -
    ----- --------------------
    -----------------
  - ----- ----- -
    ----------------------
    ---------------
  -
-
-------

在此应用程序中，我们注册了 fastify-swagger 插件，并将 Swagger UI 的路由前缀设置为 /documentation。在 Swagger 对象中，我们设置了 API 文档的基本信息，例如标题、版本等。我们还设置了 API 的主机地址和使用的协议、请求和响应的数据类型等。

最后，我们使用 fastify-autoload 自动导入 routes/ 目录下的所有路由文件。我们使用 fastify.swagger() 方法启用 Swagger UI。

编写路由

以下是 routes/ 目录下的示例代码 index.js：

const fp = require('fastify-plugin')

module.exports = fp(async (fastify, opts) => {
  fastify.get('/', async (request, reply) => {
    return { hello: 'world' }
  })
})

运行应用程序

现在，可以运行应用程序了：使用以下命令启动服务器：

node app.js

然后，通过浏览器访问 http://localhost:3000/documentation，即可查看 Swagger UI 界面。

如果一切正常，您将看到生成的 API 文档和漂亮的交互式用户界面。

如何使用 Swagger UI

通过 Swagger UI，您可以在网页上直接测试和调试 API。在 Swagger UI 界面中，您可以：

浏览 API 的路径和操作
查看 API 定义
测试 API

例如，使用以下命令在 Fastify 应用程序中设置一个 POST 路径 /api/login：

fastify.post('/api/login', async(request, reply) => {
  const { username, password } = request.body
  // TODO: Authenticate user

  return { message: 'Success' }
})

接下来，使用 Swagger UI 进行测试：

在 Swagger UI 页面的右上角选择 POST /api/login
在 Request body 中，输入以下 JSON 数据：

{
  "username": "test",
  "password": "password"
}

点击 Try it Out 并等待请求完成。
在下面的 Response 部分中，您将看到 200 OK 响应及其说明。

总结

本文介绍了如何在 Fastify 服务中使用 Swagger UI，以便于用户更加直观地了解和使用 API。我们介绍了 Swagger UI 的基本知识，并提供了一个示例代码，以帮助您更好地了解如何集成 Swagger UI。希望本文对您有所帮助。

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