介绍
man-api 是一个用于生成 API 文档的工具，它能够快速方便地生成 Markdown 格式的 API 文档，包括路由、请求方法、请求参数、响应参数等信息。该工具旨在提高开发效率，同时使 API 文档维护更加简单。
安装
使用 npm 进行安装：
$ npm install man-api --save-dev
快速开始
- 在项目目录下创建一个
api-docs目录； - 在
api-docs目录下创建一个api.js文件； - 在
api.js文件中编写 API 文档描述信息：
-- -------------------- ---- -------
-------------- - -
------------ -
---- -
------------ ---------
------------ -
--- -
----- ---------
--------- -----
------------ --- ---
-
--
--------------- -
----- -
----- ---------
------------ ------
--
---- -
----- ---------
------------ ------
-
-
--
----- -
------------ -------
-------------- -
----- -
----- ---------
--------- -----
------------ ------
--
---- -
----- ---------
--------- -----
------------ ------
-
--
--------------- -
--- -
----- ---------
------------ --- ---
-
-
-
-
-- 在
package.json文件中添加脚本，用于生成 API 文档：
{
"scripts": {
"docs": "man-api -s api-docs -o docs"
}
}- 在终端中执行以下命令，生成 API 文档：
$ npm run docs
- 在
docs目录中可以看到生成的 Markdown 格式的 API 文档。
使用说明
命令行选项
man-api 命令行选项如下：
-s, --source <source>：API 文档描述信息所在目录，默认为api-docs；-o, --output <output>：生成的 API 文档所在目录，默认为docs。
API 文档描述信息
man-api 支持以下信息的描述：
路由
'/user/:id': {
// ...
}请求方法
'/user/:id': {
get: {
// ...
},
post: {
// ...
}
}支持的请求方法有：get、post、put、delete、head、options。
请求参数
-- -------------------- ---- -------
------------ -
---- -
-- ---
------------ -
--- -
----- ---------
--------- -----
------------ --- ---
-
--
-------------- -
-- ---
-
-
-请求参数的结构如下：
-- -------------------- ---- -------
-
-- ---
---------- -
-- ----
----- ---------
-- ----
--------- -----
-- ----
------------ --------
-
-响应参数
-- -------------------- ---- -------
------------ -
---- -
-- ---
--------------- -
----- -
----- ---------
------------ ------
--
---- -
----- ---------
------------ ------
-
-
-
-响应参数的结构与请求参数类似。
示例代码
-- -------------------- ---- -------
------------ -
---- -
-- ---
--------- -
-- -- -
----------------- -
-- ----
------- -
--- ------
--
-- ----
--------- -
----- -----
---- --
-
--
-- -- -
----------------- -
-- ----
------- -
--- ------
--
-- ----
--------- -
----- -----
---- --
-
-
-
-
-总结
man-api 是一个非常方便的 API 文档生成工具，可以极大地提高开发效率，同时也能使 API 文档维护更加简单！
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/76091