前言
随着 Web 应用越来越复杂，后台的数据结构也越来越庞大，人工维护代码文档往往变得异常繁琐。Swagger 是一种非常流行的 API 文档生成工具，同时也是一种 API 客户端调用工具。在 Node.js 后端开发过程中，常常会用到 knex 和 objection 等数据库客户端。objection-swagger 就是针对 objection 数据库提供的一个 NPM 包，可以根据我们定义的 objection 模型，自动生成 swagger 文档。
前置条件
- Node.js 版本 v8.16.0 及以上；
- 使用 objection 或 knex.js。
安装
你可以直接使用 npm 进行安装，并把成果应用在你的 application 中:
npm install objection objection-swagger
生成标注
为了使用 Swagger 能够描述模型，我们需要为模型添加详细的标注。下面是一些基础标注的示例：
-- -------------------- ---- -------
------ - ----- - ---- ------------
----- ------ ------- ----- -
-- ----- ---- -- --- ---- -------- ---------
------ --- ----------- -
------ ----------
-
-- ------------ -----------
------ --- ------------ -
------ -
----- ---------
--------- ------------- ------------
----------- -
--- - ----- --------- --
--------- - ----- ----------- ------- --
---------- - ----- --------- ---------- -- ---------- --- --
--------- - ----- --------- ---------- -- ---------- --- --
---- - ----- -------- --
-- ---------- ------- -- ------- -- ------ ---
-- ------------- --------- -- ---- ------- ----
-- ------- -- -------- --- ---- -- ------- ---
-- ------ ---- ------- ---- --------- -- --------
-- ---- --------- ---- -------- ----- ----------
-------- -
----- ---------
----------- -
------- - ----- -------- --
----- - ----- -------- --
-------- - ----- -------- -
-
-
-
--
-
-- ---- ------ ------- --- --------- -- ----- -------
------ --- ------------------ -
-- --------- ------ ---- -- - --- --- -- ----- ------- ------
----- ------ - --------------------
----- ----- - -------------------
----- ----------- - -------------------------
----- --- - -----------------
------ -
----- -
--------- -------------------------
----------- ----
----- -
----- -------------
-------- -
-- -------------- -- --- ---- ------
----- --------------------------
--- ------------------------
--
--- --------------
-
--
-- ---------- --------- ------ --- ---- -------- -------- -------
--------------- -
--------- -------------------------
-- -- --- --- ------- ----- ---- ------- ---------------- -- -------
-- -- --- ------- ------ --- ------------ -------- ----- ------------
-- ---- --- ---------- -- --- ------- ------
----------- ------
----- -
-- ------------ -- -------------------------
----- -------------
-- ----------- -- ------------------------
-------- -
----- --------------------------
--- ------------------------
--
-- ----------- -- ------------------------
--- -----------
-
--
-- --------- --------- ------ --- ---- --- -------
------- -
--------- ---------------------------
----------- -------
----- -
----- -------------------
--- ------------
-
--
-- --------- --------- ------ --- ---- -------- ---------
--------- -
--------- ----------------------
----------- -------
----- -
----- -------------
--- ------------------
-
-
--
-
-- ---- ------ ---
-在上述代码中，我们可以看到，我们定义了一些 objection 模型的基本信息。其中包括了表名、jsonSchema 验证、关联关系等信息。
生成 Swagger 文档
继承完 objection 框架之后，我们需要安装 swagger-routes-express 作为路由插件的基础，然后通过 objection-swagger 自动生成 swagger 文档。代码示例如下：
-- -------------------- ---- ------- ----- ------- - ------------------- ----- --------- - ------------------------------ ----- - ----- - - --------------------- ----- ---- - ---------------- ----- ---------- - ---------------------- ----- - ------------------- - - ----------------------------- ----- ---- - ----------------------------- ----- --- - ---------- -- -------- ------------ ------ ----------------- -- -------- ------ ----- ------ - --------------------- ---- ------ --- ------------ ---- --- -- ------ --- ------------- ---------------- ---------------- ------------------------------ -- ----- --- ------ ---------------- -- -- ------------------- ------- -- ------------------
在上述代码中，我们使用 express 注册了 swagger-ui-express，并通过 objection-swagger 自动生成了 swagger 文档。这里我们需要注意的是，我们需要通过 Model.knex() 注册我们的 objection.js 模型，在项目中使用需要确保数据库连接已经建立。
生成的 Swagger 文档
最后，我们进入 localhost:3000/docs 后，可以看到自动生成的 Swagger 文档，其中包括了模型、验证、查询、删除等相关信息。整个流程如下所示：
结语
本文介绍了如何使用 objection-swagger 自动生成 swagger 文档，以及如何在 express 路由中使用。如果你想要更加深入地了解 Swagger、objection-swagger 相关的内容，可以参考相关文档进行研究。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/objection-swagger