使用apidoc 生成Api接口文档

前言：

在项目开发过程中，总会牵扯到接口文档的设计与编写，不管是使用word文档，还是git上markdown编写md文档，在界面显示上不够漂亮和直观，并且布局也花费很大的时间。apidoc是一个轻量级的在线接口文档生成系统，仅需要按照要求书写相关注释，就可以生成可读性好、界面美观的在线接口文档

---

一、apidoc的基本概念

apoDoc是从源码的注释中生成RestFul api 文档，样子还是蛮漂亮的……

1.1、我们选用JavaDoc-Style注释样式:

**
 1. @api {get} /user/:id Request User information
 2. @apiName GetUser
 3. @apiGroup User
 4.  5. @apiParam {Number} id Users unique ID.
 5.  7. @apiSuccess {String} firstname Firstname of the User.
 6. @apiSuccess {String} lastname  Lastname of the User.
 */

1.2、安装apiDoc

   1、apidoc是基于nodeJs平台，在安装apidoc之前，需要先安装nodeJs。
   2、npm install apidoc -g //全局安装apidoc
   3、apidoc -v命令，apidoc是否安装成功。 

1.3、常用的命令格式如下:

  apidoc -i myapp/ -o apidoc/  把myapp中的配置和注释生成到apidoc文件下

1.4、使用apidoc 生成Api接口文档

  1、创建开发文件夹src（或者自己定义名，命令编译的时候文件名写对就可以了）
       mkdir src
  2、创建代码文件夹的根目录
       mkdir Bschool
  3、每个根目录文件下创建apidoc.json文件。
         {
            "name": "B端学校", 
            "version": "1.0.0",
            "description": "B端学校->详情->具体详情页",
            "title": "AiJianZiPlatform",
            "url" : "后台http"
          }
   4、每个根目录文件下还需创建example.java文件
     /**
     * @api {POST} /province 获取省份
     * @apiGroup Bschool
     * @apiVersion 0.0.1
     * @apiDescription 用于B端学校获取学校的省份列表

     * @apiParam (Request Params) {String} [schoolId] 学校id

     * @apiSuccess (200) {String} msg 信息
     * @apiSuccess (200) {int} code 0 代表无错误 1代表有错误
     * @apiSuccessExample {json} 返回样例:
     *                {"code":"0","msg":"修改成功"}
     */
   5、apidoc -i 开发文件的路径 -o 生成文件的路径

      apidoc -i src/Bschool -o apidoc/Bschool
   6、打开项目文件夹下的index.html可以查看效果

二、apidoc的apidoc.json 和注释文件的注释都是什么含义

apidoc文档

• 文件目录结果如下图所示。
  

    文件解析：
     apidoc.json：apidoc的项目配置文件，文件名不可更改。
     {
        "name": "bSchool",     //项目名
        "version": "1.0.0",     //项目文档的版本号
        "description": "b端学校",    //详细描述
        "title": "bSchool",              //文档标题，显示在文档界面的最上方
        "url": "https://api.github.com/v1",  
        // 整个api url的前缀，接下来的所有接口url都会加上这个前缀。
        用来区分不同系统的api端口和api的ip前缀
     }
     bSchool.java：源文件，pidoc会搜索整个工程目录选择所有可能的源文件,  
                   可以建立好几个源文件。

• apidoc参数（params）的书写

     1、@api {请求的HTTP方法名}  url path [接口名]
          @api {POST} /province 获取省份
     2、@apiDescription 具体的描述内容
          @apiDescription 用于B端学校获取学校的省份列表
     3、@apiGroup name name不支持中文，一旦输入中文，  
            apidoc就会忽略这些中文字符。如果需要在界面中显示中文接口组名
          @apiGroup Bschool
     4、@apiParam 请求参数类型。  
        例如 {Boolean}, {Number}, {String}, {Object}, {String[]}
          @apiParam [(group)] [{type}] [field=defaultValue] [description]
          @apiParam (Request Params) {String} [schoolId] 学校id
     5、@apiSuccess
          @apiSuccess [(group)] [{type}] field [description]
          * @apiSuccess (200) {int} code 0 代表无错误 1代表有错误
     6、 @apiSampleRequest /province
        表示一个接口测试块，根据定义的请求参数来生成一个表单进行接口测试。