在前端开发中，我们需要对接后端的 API 接口，而后端文档的编写比较繁琐，让前端来写更为方便快捷。swagger-jsdoc 便是一款将 api 文档转换成 swagger 文档的工具。本篇文章将为读者详细讲解如何使用 swagger-jsdoc 这个 npm 包。
安装
使用 npm 安装 swagger-jsdoc
npm install swagger-jsdoc
使用
第一步：定义接口文档
在后端定义 API 接口文档，使用 JSDoc 注释格式。如下：
-- -------------------- ---- ------- --- - -------- - ------- - ---- - ------------ --------- - ---------- - ---- - ------------ -------- - ------- - ----- ----- - ------ - ----- -------------------- - ----- - ------------ ------- - ----------- - - ----- ---- - ------------ --- - --- -------- - ----- ------ - - ----- --- - ------------ ---- - --- -------- - ----- ------- - ---------- - ---- - ------------ ------ - ------- - ----- -------------------- --
第二步：使用 swagger-jsdoc
在前端代码中使用 swagger-jsdoc 将接口文档转换成 swagger 文档。如下：
-- -------------------- ---- -------
----- ------------ - -------------------------
----- ------- - -
------------------ -
----- -
------ ----- -----
-------- --------
------------ ---- --- ---- -------------
--
--------- -------
--
----- ---------------------
--
----- ----------- - ----------------------其中，options 是 swagger-jsdoc 的选项，swaggerDefinition 定义了 swagger 的基本信息，如标题、版本和描述等。而 apis 则是要转换成 swagger 的接口文档所在的位置。
第三步：使用 swagger-ui
接下来，我们将使用 swagger-ui 来解析并展示生成的 swagger 文档。在以下代码中，swaggerJson 即是前文中生成的 swaggerSpec。如下：
-- -------------------- ---- -------
--------- -----
------
------
-------------- ----------
----- --------------- ---------------- ---------------------- --
-------
------
---- ----------------------
---- ------- -- ---
------- ---------------------------- ---------
------- --------------------------------------- ---------
--------
----- -- - -----------------
----- ------------
------- --------------
-------- -------------------------------
------- -------------
------------ -----
--------------- -----
--------------------- -----
---
---------
-------
-------示例代码
以下为完整示例代码：
-- -------------------- ---- -------
----- ------- - -------------------
----- ---------- - -----------------------
----- ------------ - -------------------------
----- --------- - ------------------------------
----- --- - ----------
---------------------------
-- ------
---
- --------
- -------
- ----
- ------------ ---------
- ----------
- ----
- ------------ --------
- -------
- ----- -----
- ------
- ----- --------------------
- -----
- ------------ -------
- -----------
- - ----- ----
- ------------ ---
- --- --------
- ----- ------
- - ----- ---
- ------------ ----
- --- --------
- ----- -------
- ----------
- ----
- ------------ ------
- -------
- ----- --------------------
--
-- -- ------
---
- --------
- -----------
- -----
- -----------
- ---
- ----- ------
- ------------ -- --
- -----
- ----- ------
- ------------ ---
- ----
- ----- -------
- ------------ ----
--
-- ------------- ----
----- ------- - -
------------------ -
----- -
------ ----- -----
-------- --------
------------ ---- --- ---- -------------
--
--------- -------
--
----- -------------
--
-- -- ------------- --
----- ----------- - ----------------------
-- -- ---------- -------
-------------------- ---------------- ------------------------------
-- --- ------
--------------------- ----- ---- -- -
----------
-
--- ----
----- ------
---- ---
--
-
--- ----
----- --------
---- ---
--
---
---
-- ---- ------
---------------------- ----- ---- -- -
----- - ----- --- - - ---------
----------
--- ----
-----
----
---
---
-- ----
---------------- -- -- -
-------------------- ------ -- --------- -- ---- ------------------------
---总结
本篇文章针对前端使用 swagger-jsdoc 这个 npm 包进行接口文档转换的流程进行了详细的讲解。当我们将接口文档转换成 swagger 文档后，再使用 swagger-ui 来展示其生成的文档，可以大大提高接口文档的编写效率。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/79737