在前后端分离的项目中，接口文档对于开发效率和代码可读性都非常重要，而生成接口文档也是一项枯燥并容易出错的工作。本文将介绍如何在 Mongoose 中使用 OpenAPI 和 Swagger 自动生成 API 文档，以提高生成接口文档的效率和准确性。
什么是 OpenAPI 和 Swagger
OpenAPI（原名 Swagger）是一个用于 RESTful API 的规范和工具集。OpenAPI 旨在定义 RESTful API 的接口描述、请求和响应参数、返回格式等详细规范，使得开发者可以更加快速和准确地开发和使用 RESTful API。
Swagger 是 OpenAPI 规范的实现和工具集，它可以根据 OpenAPI 规范自动生成 API 文档，依照请求参数和响应数据格式自动生成代码示例，支持多种编程语言和框架。
如何集成 OpenAPI 和 Swagger
- 在项目中安装
express-openapi-validator和swagger-ui-express库，分别用于 OpenAPI 验证和 Swagger UI 展示。
npm install express-openapi-validator swagger-ui-express
在项目中创建
api.yml文件，用于描述 RESTful API 的接口文档，具体格式可参考 OpenAPI 规范。创建一个
swagger.js文件，通过swaggerUi.setup和swaggerUi.serve将 Swagger UI 集成到应用中。
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./api.yml');
module.exports = (app) => {
app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
};- 在
app.js文件中使用express-openapi-validator中间件，从api.yml中读取接口文档并自动验证请求和响应的参数格式和类型。
-- -------------------- ---- ------- ----- ---- - ---------------- ----- ------- - ------------------- ----- - ---------------- - - ------------------------------------- ----- --------- - --------------------- ----- --- - ---------- -- -- ------- --------- --------------- --- ------------------ -------- ----------------------- ------------- ---------------- -- - ------- -- ------ --------------- -- ---- --------- ---------------- -- -- - ------------------- -- --------- -- ---- ------- ---
如何在 Mongoose 中使用 OpenAPI 和 Swagger
以一个简单的 Mongoose 模型 User 为例，演示如何在接口文档中定义和描述一个 RESTful API。
创建 Mongoose 模型
-- -------------------- ---- ------- ----- -------- - -------------------- ----- ---------- - --- ----------------- ----- ------- ---- ------- --- ----- ---- - ---------------------- ------------ -------------- - -----
定义 RESTful API 接口文档
在 api.yml 文件中，将 RESTful API 的接口文档定义为以下格式：
-- -------------------- ---- -------
-------- -----
-----
------ ------ ---
------------ ---- --- -------
-------- -----
--------
- ---- ---------------------
------
-------
----
-------- --- --- -----
----------
----
------------ --
--------
-----------------
-------
----- -----
------
----- ---------------------------
-----
-------- ------ - ----
------------
--------
-----------------
-------
----- ---------------------------
----------
----
------------ -------
--------
-----------------
-------
----- ---------------------------
------------
----
-------- --- - ---- -- --
-----------
- --- ----
----- --
--------- ----
-------
----- ------
------------ ---- --
----------
----
------------ --
--------
-----------------
-------
----- ---------------------------
-------
-------- ------ - ---- -- --
-----------
- --- ----
----- --
--------- ----
-------
----- ------
------------ ---- --
----------
----
------------ -- -------
-----------
--------
-----
----- ------
-----------
-----
----- ------
----
----- -------该接口文档描述了一个简单的用户管理 API，包含三个接口：
- GET /users: 获取所有用户的信息，返回值是用户对象数组，每个用户对象包含 name 和 age 属性。
- POST /users: 创建一个用户对象，请求体是用户对象，返回值是创建成功后用户对象。
- GET /users/{id}: 获取指定 id 的用户对象，请求参数是用户 id，返回值是指定 id 的用户对象。
- DELETE /users/{id}: 删除指定 id 的用户对象，请求参数是用户 id，无返回值。
编写通过 OpenAPI 验证的 Mongoose API 代码
在路由中使用 validateRequest 和 validateResponse 挂载 OpenAPI 验证的中间件，同时使用 Mongoose 编写接口逻辑代码。
-- -------------------- ---- ------- ----- ------- - ------------------- ----- - ---------------- ---------------- - - ------------------------------------- ----- ---- - ------------------------- ----- ------ - ----------------- --------------- ----- ----- ---- -- - ----- ----- - ----- ------------ ---------------- --- ---------------- ----- ----- ---- -- - ----- ---- - ----- ---------------------- --------------------------- --- ------------------ ----- ----- ---- -- - ----- - -- - - ----------- ----- ---- - ----- ------------------ --------------- --- --------------------- ----- ----- ---- -- - ----- - -- - - ----------- ----- --------------------------- -------------------- --- ------------------------------ ------------------------------- -------------- - -------
如何使用 Swagger 自动生成代码示例
使用 Swagger 的 x-codeSamples 扩展字段可以自动生成多种编程语言和框架的代码示例。在 api.yml 文件中为每个接口添加 x-codeSamples 字段，下面是一个简单的 Node.js 示例：
-- -------------------- ---- -------
------
-------
----
-------- --- --- -----
----------
----
------------ --
--------
-----------------
-------
----- -----
------
----- ---------------------------
--------------
- ----- ------
------ -----
------- -
----- ----- - -----------------
----------------------------------------
---------------- -- ----------------------
-------------- -- ----------------------在 Swagger UI 中可以看到：
总结
使用 OpenAPI 和 Swagger 可以使得文档编写、代码示例生成和接口验证等流程更加自动化和规范化，减少了手写文档和代码的错误率和时间消耗，提高了开发效率和代码质量。当然，在编写接口文档时，也需要同时注意文档的详细程度和准确性。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/651d20ab95b1f8cacd4a53e4