在前端开发中，我们经常需要生成 API 文档或者测试数据，一般的做法是手动复制粘贴，这样很麻烦且容易出错。而 swag 这个 npm 包可以帮助我们自动生成 API 文档或者测试数据，提高开发效率。
什么是 swag
swag 是一个用于解析 Go 代码中注释的工具，然后自动生成文档或者测试数据。由于注释的规范是和 Swagger 一致的，因此也称为 Swagger for Go。
不过 swag 并不仅仅限于 Go 语言，你只需要用它要求的注释规范编写注释，在任何语言中都可以使用 swag 生成对应的文档。
swag 的基本使用方法
# 安装 swag npm install -g swag # 生成文档 swag init
使用 swag 非常简单，只需要全局安装 swag，然后在你的项目根目录下运行 swag init 命令即可生成文档。
swag 会读取你代码中的注释，然后自动生成文档，并将文档保存在项目目录下的 docs 文件夹中。生成文档的格式和名字也可以自由定义。
假设我们的项目根目录下有一个 main.go 文件：
-- -------------------- ---- -------
------- ----
------ --------------------------
-- -------- ---- --- ----
-- ------------ ------ --- - --- ----
-- ----- --- ----
-- ------- ----
-- -------- ----
-- ------ ---- ----- ------ ---- ---- ---- -- ----------
-- -------- --- -------- ---- --------------------------- -------
-- -------- --- -------- ---- ----------------------- ----------
-- -------- --- -------- ---- -------------------------- --------
-- ------- ----- -----
---- ------ -
- -- -------------
-------------- ------ ------------- -
----------- ------
------- ----
------- ------- ------
--
--
------- -- ------ --- ----- -- ------------
-然后我们在项目根目录下运行 swag init 命令即可生成文档。生成的文档如下图所示：
swag 更高级的用法
除了基本的用法之外，swag 还提供了很多高级用法，让我们能够更加灵活地使用 swag。
使用 swag 获取程序信息
在一些情况下，我们需要获取程序的一些信息，比如程序的版本号、作者等。这个时候，我们可以使用 swag 通过注释来获取相关信息。
-- -------------------- ---- -------
-- ------ -- ------- ---
-- -------- ---
-- ------------ ---- -- -- ------- ----
-- --------------- --------------------------
-- -------- ----------- ------------------------
-- -------- ---------- ----------------------------------------------------------
-- ----- --------------
-- --------- -------
---- ------ -
-- ---
-swag 会根据注释中的信息，生成对应的文档。
使用 swag 生成测试数据
有时候我们需要为接口生成一些测试数据，来测试接口的正确性。这个时候，swag 也可以帮助我们生成测试数据。
-- -------------------- ---- -------
-- ------ -- ------- ---
-- -------- ---
-- ------------ ---- -- -- ------- ----
-- --------------- --------------------------
-- -------- ----------- ------------------------
-- -------- ---------- ----------------------------------------------------------
-- ----- --------------
-- --------- -------
---- ------ -
-- ----- ---- ----------
---- ---- ------ -
-- --- -----------
---- ------ -------------
-
---- -- -------- -- ----- --------
-- -- ---- ----------- ----
------------------------------
-运行上面的代码可以得到下面的输出：
{
"id": 1,
"name": "Alice"
}自定义生成文档的格式和语言
swag 默认可以生成 Markdown 和 ReStructuredText 格式的文档，同时也支持自定义生成的文档格式和语言。
这里以自定义文档语言为例，介绍 swag 的高级用法。首先，我们需要安装一个额外的依赖，用于生成不同语言的文档。这里演示的是安装 swagdoc 依赖。
# 安装 swagdoc npm i swagdoc
然后修改项目根目录下的 docs.go 文件，内容如下：
-- -------------------- ---- -------
-------- --------
------- ----
-- ------ -- ------- ---
-- -------- -
-- ------------ ---- -- -- ------- ----
------ -
------------------------
----------------------------
------------------------------------
-
---- ------ -
---------- -- --------
------------------------ ---------------- -- -----
----- ----------
-------------- ------ ------- ----------- ------ -
-- -------------
------ ---- ---
--
---------------- ------ ---------------- -------- ------ -
-- ----- ------- ----
------ -------------------------
--
---- --------- --- -------------- -- --------- ---- ------
-------------- ------ ----------- -
------ ----------------
------------ -----------------
------ --- ------- -----
-------- ----
------------ ----- -- -- ------- ------
--
---------- ----------------
-- --------------
----- -----
------- -----
--
-- --------------
----- --------
------- --------
--
--
-
--
--
----------------------- ------- ----- ---- ----- -- -- ------- ------ ------ ---
-然后在项目根目录下运行 swag init 命令即可生成包含中文文档的文档目录。
总结
swag 是一个很方便的工具，可以帮助我们自动生成 API 文档或者测试数据，提高开发效率。本文介绍了 swag 的基本用法和高级用法，希望对大家有所帮助。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/5eedcbb6b5cbfe1ea061266f