apiDoc - 超简单的文档生成器

ゞ浴缸里的玫瑰 2023-07-13 12:17 40阅读 0赞

大家所熟知的API文档有swagger等, 今天给大家推荐一个写注释就能生成文档的工具, 真的很简单! [http://apidocjs.com/][http_apidocjs.com]

## 快速开始 ##

第一步, 老规矩~装环境~

npm install apidoc -g

第二步, 新建一个项目

![format_png][]

文件结构

src: 打算放注释文档的文件, 先只建一个文件(file1.js, 不用纠结这些注释含义, 后面会详解)代码如下

/**
     * @api {Get} /user/get getUserInfo
     * @apiGroup User
     *
     * @apiParam {String} name 文章名
     * @apiParamExample {json} Request-Example
     * {
     *  "userName": "Eve"
     * }
     *
     * @apiSuccessExample  {json} Response-Example
     * {
     *   "userName": "Eve",
     *   "createTime": "1568901681"
     *   "updateTime": "1568901681"
     * }
     */
    function getUserInfo(username) {
      // 假如这个函数是根据用户名返回用户信息的
    }

apidoc.json: 文档配置文件, 示例代码如下.

{
      "name": "apidoc-demo",
      "description": "You write something here to describe your project",
      "title": "The title of this doc"
    }

第三步, 执行命令. -i是指注释文件存放的地方, -o是指文档输出的位置

apidoc -i src/ -o apidoc/

接下来我们会发现多了一个文件夹`**apidoc**`. 这是自动生成的一个文件夹目录

![format_png 1][]

多了一个文件夹

里面放的就是API文档, 里面有一个index.html, 我们双击打开.

![format_png 2][]

apidoc/index.html

这3个部分眼熟么? 没错! 这就是我们一开始定义的apidoc.json里面的配置文件. 简单三步即可生成一份API文档, 算是挺傻瓜式的了.

## apidoc.json详解 ##

作为apiDoc的配置文件, 采用了JSON的方式定义数据结构.官方给出了非常详细的说明, 具体见下表.

![format_png 3][]

相信这些参数大家都能理解, 在这里我简单演示下header与footer的用法

## header与footer ##

有时候除了正经的文档, 我们有一些话要写在开头或结尾, 如一些约定格式.

第一步: 新建头尾文件(官方要求是md文件)

![format_png 4][]

第二步: 修改配置文件

{
      "name": "apidoc-demo",
      "description": "You write something here to describe your project",
      "title": "The title of this doc",
      "header": {
        "title": "文档说明",
        "filename": "header.md"
      },
      "footer": {
        "title": "文档结尾",
        "filename": "footer.md"
      }
    }

再次执行 **apidoc -i src/ -o apidoc/** 重新生成文档

(API内容少了, 因为故意删去了file1.js里的内容, 方便截图)

![format_png 5][]

如果你使用了package.json来管理项目, 你可以将apidoc.json放在package.json里面, 以"apidoc"为key即可.

{
      "name": "apidoc-demo",
      "version": "1.0.0",
      "description": "",
      "main": "index.js",
      "author": "Eve",
      "license": "MIT",
      "apidoc": {
        "name": "apidoc-demo",
        "description": "You write something here to describe your project",
        "title": "The title of this doc",
        "header": {
          "title": "文档说明",
          "filename": "header.md"
        },
        "footer": {
          "title": "文档结尾",
          "filename": "footer.md"
        }
      }
    }

## 注释详解 ##

接下来讲讲核心的注释参数

![format_png 6][]

通过这些注释关键字, apidoc的渲染引擎会将你的注释解析成文档, 所以我们要做的就是按照他的规则去写注释.

## 常用注释 ##

虽然官方罗列了一大堆关键字, 但实际上高频使用的关键字很少, 就那么几个

这个过程其实并不难, 下面我列出了常用的文档注释与效果图, 简单对比之后你应该就能get如何去写一个基础的文档.

/**
     * @api {方法} 路径 标题
     * @apiGroup Group
     * @apiDescription 描述这个API的信息
     *
     * @apiParam {String} userName 用户名
     * @apiParamExample {json} request-example
     * {
     *  "userName": "Eve"
     * }
     *
     * @apiError {String} message 错误信息
     * @apiErrorExample  {json} error-example
     * {
     *   "message": "用户名不存在"
     * }
     * 
     * 
     * @apiSuccess {String} userName 用户名
     * @apiSuccess {String} createTime 创建时间
     * @apiSuccess {String} updateTime 更新时间
     * @apiSuccessExample  {json} success-example
     * {
     *   "userName": "Eve",
     *   "createTime": "1568901681"
     *   "updateTime": "1568901681"
     * }
     */
    function getUserInfo(username) {
      // 假如这个函数是根据用户名返回用户信息的
    }

上面这份注释所对应的效果图如下

![format_png 7][]

code and doc

## 定义常用参数 ##

像前文中所提到的response里的createTime与updateTime, 应该是比较常用的数据结构, 不仅是用户信息, 实体一般都具备这两个字段. apiDoc允许你将这些常用的进行『定义』, 然后在注释当中『使用』 我们新建一个define.js(名字可以任意取, 在src当中就ok)

/**
     * @apiDefine Time
     * @apiSuccess {String} createTime 创建时间
     * @apiSuccess {String} updateTime 更新时间
     */

修改前文注释中对应的对方

/**
     * @apiSuccess {String} userName 用户名
     * @apiUse Time
     * @apiSuccessExample  {json} success-example
     * {
     *   "userName": "Eve",
     *   "createTime": "1568901681"
     *   "updateTime": "1568901681"
     * }
     */

## 结语 ##

这篇文章主要目的是向大家介绍这个工具, 起到快速入门的目的. 这款工具有许多的细节如自定义状态码, 过期API, 权限管理等, 因官网解释已经足够通俗易懂, 就不再此赘述了.建议移步官方[http://apidocjs.com/][http_apidocjs.com]

[http_apidocjs.com]: https://link.zhihu.com/?target=http%3A//apidocjs.com/
[format_png]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9waWMyLnpoaW1nLmNvbS84MC92Mi05NWM0OTg1OTExMjc3YjJiNDI0NjE5N2JjNTM1NDA2OV83MjB3LmpwZw?x-oss-process=image/format,png
[format_png 1]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9waWMzLnpoaW1nLmNvbS84MC92Mi0wYTdlODJmNGFhMDg5MDYyZWFjNTdhOWVjOWY1ZGU0ZV83MjB3LmpwZw?x-oss-process=image/format,png
[format_png 2]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9waWMxLnpoaW1nLmNvbS84MC92Mi04OTBmY2QwOTEzY2UwZTA3MWNjMzUxYzM3YzZhZjIzNF83MjB3LmpwZw?x-oss-process=image/format,png
[format_png 3]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9waWMyLnpoaW1nLmNvbS84MC92Mi04ODg3NTE0ZTNlM2U5NTFhZTMwMThkNmIxMjI5MThlMV83MjB3LmpwZw?x-oss-process=image/format,png
[format_png 4]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9waWM0LnpoaW1nLmNvbS84MC92Mi00MmY5MDliNjI1NWI2YmZlYjE2YTY4Yjc3ZjUxMjczM183MjB3LnBuZw?x-oss-process=image/format,png
[format_png 5]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9waWM0LnpoaW1nLmNvbS84MC92Mi02YTA1MTg1ZGU2MjkxYjZhNzQ1NDQyOTk2ZDY1MGM3Zl83MjB3LmpwZw?x-oss-process=image/format,png
[format_png 6]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9waWM0LnpoaW1nLmNvbS84MC92Mi1iZjBiNGRiM2UwOWYwNTQzNDJhNzY0ZDk0ZDYwZGI2Yl83MjB3LmpwZw?x-oss-process=image/format,png
[format_png 7]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9waWMzLnpoaW1nLmNvbS84MC92Mi1jOTBiNDNiZWNiYzkyNDhhMjllODFkYjZjNmFlMTI5Nl83MjB3LmpwZw?x-oss-process=image/format,png