Swagger 是一种 API 文档规范，可帮助开发人员更好地编写和测试 API。在 Express.js 应用程序中集成 Swagger 文档可以使开发人员更好地理解和使用 API，同时也可以帮助团队更好地协作和维护应用程序。
安装 Swagger
要在 Express.js 应用程序中集成 Swagger 文档，首先需要安装 Swagger。可以使用 npm 包管理器安装 Swagger：
npm install swagger-ui-express swagger-jsdoc
安装完成后，需要在应用程序中添加以下代码：
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));这个代码将 Swagger UI 添加到应用程序的 /api-docs 路径，并使用 swagger.json 文件提供 Swagger 规范。
编写 Swagger 规范
要编写 Swagger 规范，需要创建一个 swagger.json 文件，该文件描述了所有可用的 API 路径和参数。以下是一个简单的示例：
-- -------------------- ---- -------
-
---------- ------
------- -
---------- --------
-------- --- ----
--
-------- -
--------- -
------ -
---------- ---- - ---- -- --- -------
------------ -
------ -
-------------- -- ---- -- --- -------
--------- -
------- --------
-------- -
------- ---------
------------- -
----- -
------- ---------
--
------- -
------- --------
-
-
-
-
-
-
-
-
-
-在这个示例中，我们定义了一个 /users 路径，该路径支持 GET 请求，并返回一个包含用户列表的 JSON 数组。
要编写完整的 Swagger 规范，需要了解 Swagger 规范的所有属性和选项。可以在 Swagger 规范文档 中找到完整的文档。
使用 Swagger 编写更好的 API
使用 Swagger 规范编写 API 可以帮助开发人员更好地理解和使用 API。以下是一些使用 Swagger 编写更好的 API 的提示：
- 使用清晰的路径和参数名称，以便开发人员可以轻松理解 API 的用途和功能。
- 使用详细的摘要和描述，以便开发人员可以了解 API 的详细信息和使用方式。
- 使用正确的响应代码和描述，以便开发人员可以了解 API 的成功和失败情况。
- 使用正确的数据类型和格式，以便开发人员可以正确地解析和使用 API 的响应。
结论
在 Express.js 应用程序中集成 Swagger 文档可以使开发人员更好地理解和使用 API，同时也可以帮助团队更好地协作和维护应用程序。通过编写清晰的 Swagger 规范，可以让 API 更易于使用和维护。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6742e20a99516187acd9ba6a