ApiDoc 后端接口注释文档的使用

前端和后端注释文档生成

前端和后端的 函数及api 说明文档生成总结,持续更新中 by Qzx

参考网址

  • jsDoc - 中文说明
  • jsDoc 使用教程
  • 后台接口文档生成器 - APIDOC官网
  • apiDoc - 中文说明

apiDoc的使用教程

一、安装

# 全局安装
npm install apidoc -g   
# 查看是否安装成功,显示命令行参数
apidoc -h 

二、apidoc 常用命令说明

指令简写 指令全称 说明
-f --file-filters 过滤器,指定应该解析的文件类型,后缀 (可以使用多个-f)。默认.cs .dart .erl .go .java .js .php .py .rb .ts。示例(仅解析.js和.ts文件):apidoc -f ".*\.js" -f ".*\\.ts"
-e --exclude-filters 过滤器用于选择不应该解析的文件
-i --input 指定输入的源目录名,项目文件的位置,默认为 ./ 例:apidoc -i myapp/
-o --output 指定输出的目录文件名,放置生成文档的位置,默认为 ./doc/,例:apidoc -o apidoc/
-t --template 指定要用的外部模板的路径,可以创建和使用自己的模板,默认使用全局的 node_modules/apidoc/template/ ,例:apidoc -t mytemplate/
-c --config 指定配置文件的路径 apidoc.json ./
-h --help 显示详细的帮助说明
--debug --debug 显示调试的信息,默认为 false

三、具体使用

  1. 在项目文件夹新建apidoc.json;

  2. 在项目目录运行:

    apidoc -i myapp/ -o apidoc/ -t mytemplate/
    # 简写指令
    apidoc
    

说明:上面的指令可以直接简写为 apidoc,没有任何参数时,默认从当前目录(包括子目录)下格式为(.cs .dart .erl .go .java .js .php .py .rb .ts) 的所有文件生成文档并将输出写入 ./doc/。

四、基本配置(apidoc.json)

项目根目录下的 apidoc.json 可配置项包含有关项目的常用信息,如 标题,简短描述、版本和配置选项,如页眉/页脚设置或模板特定选项。

  • 基本配置方式(apidoc.json)

    {
      "name": "example",
      "version": "0.1.0",
      "description": "apiDoc basic example",
      "title": "Custom apiDoc browser title",
      "url" : "https://api.github.com/v1"
    }
    
  • 在含有package.json文件的项目中配置(添加"apidoc":{}参数)

    {
      "name": "example",
      "version": "0.1.0",
      "description": "apiDoc basic example",
      "apidoc": {
        "title": "Custom apiDoc browser title",
        "url" : "https://api.github.com/v1"
      }
    }
    
  • 添加额外的 Header 和 Footer (不常用,在apidoc.json添加header和footer参数)

    {
      "header": {
        "title": "My own header title",
        "filename": "header.md"
      },
      "footer": {
        "title": "My own footer title",
        "filename": "footer.md"
      }
    }
    
  • 配置参数的详细说明(apidoc.json)

    参数名 描述
    name 项目名称,若不存在该字段,则会尝试取 package.json 里面的name值
    version 项目版本号,不存在则读取 package.json 里面对于的值
    description 项目描述 ,不存在同上
    title 浏览器标题文本
    url api路径的前缀,适合同一域下的接口,例:https://api.github.com/v1
    sampleUrl 测试样例的url, 具体请参考 @apiSampleRequest
    header 添加自定义的顶部描述 {title: '', filename: ''}
    title 顶部的标题
    filename 顶部具体的展现内容
    footer 添加自定义的尾部描述 {title: '', filename: ''}
    title 尾部的标题
    filename 尾部具体的展现内容
    order 用于定义输出的api-names/group-name列表排序。最后自动显示未定义的名称。"order": ["Error","Define","PostTitleAndError","PostError"]

五、apiDoc 常用api说明

  • 常用api:@api,@apiName,@apiGroup,@apiVersion,@apiDescription,@apiParam,@apiSuccess,@apiSuccessExample,@apiDefine,@apiError,@apiIgnore

  • 基本例子(demo.js)

    /**
     * @api {get} /user/:id Request User information
     * @apiVersion 0.1.0
     * @apiName GetUser
     * @apiGroup User
     *
     * @apiParam {Number} id Users unique ID.
     *
     * @apiSuccess {String} firstname Firstname of the User.
     * @apiSuccess {String} lastname  Lastname of the User.
     *
     * @apiSuccessExample Success-Response:
     *     HTTP/1.1 200 OK
     *     {
     *       "firstname": "John",
     *       "lastname": "Doe"
     *     }
     *
     * @apiError UserNotFound The id of the User was not found.
     *
     * @apiErrorExample Error-Response:
     *     HTTP/1.1 404 Not Found
     *     {
     *       "error": "UserNotFound"
     *     }
     */
    

    说明:文档块以 /***/ 结尾,其中@api为必须字段,格式同例子:@api + {请求类型} + 接口路径 + 接口描述,在生成的时候没有@api 的文档块会被忽略。@apiName@apiGroup,在版本迭代时应保持一致,其他字段为可选。

  • @api (必须字段,没有会被忽略)

    @api {method} path [title]
    

    例:@api {get} /user/:id Users unique ID.

  • @apiParam

    @apiParam [(group)] [{type}] [field=defaultValue] [description]
    

    示例:

    /**
     * @api {get} /user/:id
     * @apiParam {Number} id Users unique ID.
     */
    
    /**
     * @api {post} /user/
     * @apiParam {String} [firstname]  Optional Firstname of the User.
     * @apiParam {String} lastname     Mandatory Lastname.
     * @apiParam {String} country="DE" Mandatory with default value "DE".
     * @apiParam {Number} [age=18]     Optional Age with default 18.
     *
     * @apiParam (Login) {String} pass Only logged in users can post this.
     *                                 In generated documentation a separate
     *                                 "Login" Block will be generated.
     */
    

    说明:1. 带括号的Fieldname将Variable定义为可选。2. =defaultValue 参数默认值。

  • @apiSuccess

    @apiSuccess [(group)] [{type}] field [description]
    

    示例:

    /**
     * @api {get} /user/:id
     * @apiSuccess {String} firstname Firstname of the User.
     * @apiSuccess {String} lastname  Lastname of the User.
     */
     
     /**
      * @api {get} /user/:id
      * @apiSuccess (200) {String} firstname Firstname of the User.
      * @apiSuccess (200) {String} lastname  Lastname of the User.
      */
      
      /**
        * @api {get} /user/:id
        * @apiSuccess {Boolean} active        Specify if the account is active.
        * @apiSuccess {Object}  profile       User profile information.
        * @apiSuccess {Number}  profile.age   Users age.
        * @apiSuccess {String}  profile.image Avatar-Image.
        */
      ```
    
    

六、示例代码下载

apiDocDemo示例代码

七、demo示例效果图

ApiDoc 后端接口注释文档的使用_第1张图片
1532659983362.jpg
ApiDoc 后端接口注释文档的使用_第2张图片
1532660016333.jpg

jsDoc的使用教程

一、安装

# 全局安装方式
npm install -g jsdoc
# 查看安装是否成功
jsdoc -v
# 基本使用方式
jsdoc demo.js

二、jsdoc 常用命令说明

指令简写 指令全称 说明
-f --file-filters 过滤器,指定应该解析的文件类型,后缀 (可以使用多个-f)。默认.cs .dart .erl .go .java .js .php .py .rb .ts。示例(仅解析.js和.ts文件):apidoc -f ".*\.js" -f ".*\\.ts"
-e --exclude-filters 过滤器用于选择不应该解析的文件

三、具体使用

  • 命令行新建一个项目
mkdir jsDocDemo
cd jsDocDemo
npm init -y
  • 新建一个demo.js,代码示例如下:
/**
 * Book类,代表一个书本.
 * @constructor
 * @param {string} title - 书本的标题.
 * @param {string} author - 书本的作者.
 */
function Book(title, author) {
    this.title=title;
    this.author=author;
}
Book.prototype={
    /**
     * 获取书本的标题
     * @returns {string|*}
     */
    getTitle:function(){
        return this.title;
    },
    /**
     * 设置书本的页数
     * @param pageNum {number} 页数
     */
    setPageNum:function(pageNum){
        this.pageNum=pageNum;
    }
};
  • 命令行编译文件
jsdoc demo.js

: 默认生成在 out 目录下,更换目录可使用 -d + 文件夹路径

你可能感兴趣的:(ApiDoc 后端接口注释文档的使用)