Fastify 是一个高效、低开销且高度可定制的 Node.js Web 框架。和其他框架比起来，Fastify 有着更好的性能和稳定性表现。而 Swagger UI 是一个流行的，使用 OpenAPI 规范在 Web 上渲染交互式 API 文档的工具。Fastify 兼容 OpenAPI 规范，支持使用 Swagger UI 展示 API 文档，为开发者提供了更好的文档体验。在本文中，我们将学习如何使用 Fastify 和 Swagger UI 来展示 API 文档。
环境准备
本文将引用 Fastify 和 Swagger UI 的两个 npm 包，需要安装 Node.js 和 npm，你可以从官方网站 https://nodejs.org/ 下载并安装。
安装完毕后，请在命令行中输入以下命令安装 Fastify 和 Swagger UI：
npm i fastify swagger-ui-fastify
创建 Fastify 应用
首先，我们需要创建一个基本的 Fastify 应用，代码如下：
const fastify = require('fastify')();
fastify.listen(3000, (err, address) => {
if (err) throw err;
console.log(`Server listening on ${address}`);
});以上代码创建了一个 Fastify 实例，并在端口 3000 上启动了服务器。在本例中，我们将以该实例为基础构建 Swagger UI。
定义 API 路由
接下来，我们需要定义一些 API 路由。代码如下：
fastify.get('/ping', (req, reply) => {
reply.send('pong');
});
fastify.get('/users/:id', (req, reply) => {
const { id } = req.params;
reply.send({
id,
name: 'Tom Brady',
email: 'tom@example.com',
});
});以上代码定义了两个路由。第一个路由回应 GET /ping 请求，并返回字符串 'pong'。第二个路由回应 GET /users/:id 请求，并返回一个关于 Tom Brady 的简单对象。在实际应用中，这些路由需要更加完善和复杂。
配置 Swagger UI
Swagger UI 需要一些元数据来渲染出 API 文档的格式。可以通过在项目代码中定义一个 JSON 文件来实现。在本例中，我们将创建一个名为 swagger.json 的文件，并将其放置在项目的根目录下。文件内容如下：
{
"openapi": "3.0.0",
"info": {
"title": "Fastify-SwaggerUI Example API",
"version": "1.0.0",
"description": "A demonstration of Fastify and Swagger UI"
},
"servers": [
{
"url": "http://localhost:3000",
"description": "Local server"
}
],
"paths": {
"/ping": {
"get": {
"description": "A simple health check",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "string"
}
}
}
}
}
}
},
"/users/{id}": {
"get": {
"description": "Retrieve a user",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "User ID",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"email": {
"type": "string"
}
}
}
}
}
}
}
}
}
}
}以上文件定义了一些 OpenAPI 元数据，包括 API 的元数据以及各个端点的定义。
然后，我们需要修改 Fastify 应用，以支持 Swagger UI。代码如下：
const fastify = require('fastify')();
const swagger = require('swagger-ui-fastify');
const swaggerJson = require('./swagger.json');
fastify.register(swagger, {
swagger: swaggerJson,
prefix: '/docs',
});
fastify.get('/ping', (req, reply) => {
reply.send('pong');
});
fastify.get('/users/:id', (req, reply) => {
const { id } = req.params;
reply.send({
id,
name: 'Tom Brady',
email: 'tom@example.com',
});
});
fastify.listen(3000, (err, address) => {
if (err) throw err;
console.log(`Server listening on ${address}`);
});以上代码将 swagger.json 文件作为元数据载入 Swagger UI 插件。在注册 swagger-ui-fastify 插件时，我们指定了一些选项来控制 UI 的渲染行为。具体而言，我们指定了 Swagger UI 的路径前缀为 /docs，以及元数据文件的位置。在定义路由时，我们不再需要修改其响应的格式和结构，因为 Swagger UI 将以元数据文件为基础自动生成 API 文档。
启动服务器和访问 Swagger UI
在本例中，我们将 Fastify 应用运行在本地计算机上的端口 3000，因此可以使用浏览器访问 http://localhost:3000/docs 来查看 Swagger UI。你应该会看到 Swagger UI 中呈现的完整的 API 文档信息。你可以浏览所有的 API 端点，测试它们，甚至查看 Curl 命令以及请求和响应数据。当然，具体的呈现方式与 UI 的版本和配置相关，可能有所不同。
总结
本文中介绍了如何在 Fastify 应用中使用 Swagger UI 来展示 API 文档。在实际应用中，你会发现使用 Swagger UI 来记录和检查 API 端点是开发过程中很有帮助的。在你的自动化测试-suite 中引入 Swagger UI 就能使测试结果更加易懂，并让新加入开发者更快掌握和理解项目的 API 结构。本文所使用的代码也提供了一个可以扩展的开发基础，让你能够在自己的应用中集成 Swagger UI，并搭建你自己的文档材料。
来源：JavaScript中文网 ，转载请注明来源 本文地址：https://www.javascriptcn.com/post/65a21918add4f0e0ffa297d4