apidoc快速生成在線文檔，apidoc生成靜態文件的生成規則，原理分析，實踐

在老大的指引下，需要將系統的json文件格式轉換成apidoc的json格式，也就是json格式的重組，但是這個apidoc的生成格式是不固定的，因為apidoc有自己一套的生成規則，我需要研究一下是怎么生成的。

一、官方基礎栗子

二、理解apidoc生成靜態文檔的結構解讀

三、深入理解一下apidoc生成原理以及規則

 

一、apidoc基礎栗子

全局安裝apidoc

npm install apidoc -g

 

1、首先建立文件目錄

 

2、需要你在input文件夾里面寫上你的js部分

這個是栗子的js部分。

/**
  @api {get} /user/:id Request User information
  @apiName GetUser
  @apiGroup User
 
  @apiParam {Number} id Users unique ID.

  @apiSuccess {String} firstname Firstname of the User.
  @apiSuccess {String} lastname  Lastname of the User.
 */



 /**
  @api {post} /user/:id Create User information
  @apiName CreateUser
  @apiGroup User
 
  @apiParam {Number} id Users unique ID.

  @apiSuccess {String} data
  @apiSuccess {String} data.firstname Firstname of the User.
  @apiSuccess {String} data.first.lastname  Lastname of the User.

  @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 */
 

 

3、新建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"
}

 

4、在myapp文件夾下面運行

apidoc -i myapp/ -o apidoc/ -t mytemplate/

官網原文：Creates an apiDoc of all files within dir myapp/, uses template from dir mytemplate/ and put all output to dir apidoc/.

-i  是輸入文件的路徑 ，  -o 是輸出文件的路徑，   -t是使用模板的路徑（可缺省）

 

打開output文件夾，發現生成一個apidoc在線文檔，直接打開html就可以看到

 

打開html文件

 

 

二、理解apidoc生成靜態文檔的結構解讀

一個靜態的文檔很漂亮的生成了，但是實際控制這個現實的是api_data.js和api_project.js。但是實際上的數據顯示是由api_data.json和api_project.json這兩個json文件。

所以在支持將其他json格式轉換成api_data.json和api_project.json，把apidoc生成的這兩個文件進行替換，然后替換js文件，直接生產靜態文檔。

可以看一下api_data.json格式

 

對比一下api_data.js格式

 

很明顯就能看出來，就是在api_data.json的基礎上，封裝成了一層，加上define({ "api": api_data.json});

 api_project.json和api_project.js也是使用相同的方法封裝的。

 

 

三、深入理解一下apidoc生成原理以及規則

apidoc設計到如下的參數

 

（1）第一個是@api

@api是必須的，

@api {method} path [title]

比如

method    包括請求的方式：get，post，put，delete，等

path  表示請求的路徑。

title  （可選項）表示分組的解釋，導航。

對應的靜態頁面

（2）@apiDefine

@apiDefine name [title] [description]

表示的是：嵌入在api塊或api中的文檔塊

沒有找到對應的頁面

 

（3）@apiDeprecated

@apiDeprecated [text]

標志位api方法的反對（不對）的地方。

 

（4）@apiDescription

表示的是描述。

@apiDescription text

頁面上顯示的是：

 

 

 （5）@apiError和@apiErrorExample

表示的錯誤返回的參數

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

頁面的顯示：

 

（6）@apiGroup

這個是必填項，表示的分組。

頁面顯示的是：

 

（7）@apiHeader

表示的是：傳遞給API頭部的參數

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

發現：@apiHeader與@apiParam用法顯示上很像，但是在生成的api_data.json所在的樹形結構不一致。

，上面的紅框是@apiHeader生成的，下面的紅框是@apiParam生成的。

 

 （8）@apiParam

 表示的：傳遞給API方法的參數

頁面顯示的是：

 

 （9）@apiParamExample

表示的是：參數實例

 

頁面上的顯示：

 

 （10）@apiSuccess和@apiSuccessExample

表示的是：成功返回的參數。

 

頁面上的顯示：

 

目前主要用到了這10多個參數，還是夠完成老大要求的任務。

 

apidoc的輸入的js文件

 

/**
 * @api {get} /user/:id Read data of a User
 * @apiVersion 0.3.0
 * @apiName GetUser
 * @apiGroup User
 * @apiDeprecated use now (#Group:Name)
 *
 * @apiDescription Compare Verison 0.3.0 with 0.2.0 and you will see the green markers with new items in version 0.3.0 and red markers with removed items since 0.2.0.
 *
 * @apiHeader (User) {String} [field=1111] ceshi
 * @apiParam (header) {String} [hhhhh=aaa] The Users-ID.
 * @apiParam (query) {Number} [X=1001] Users unique key.
 * @apiParam (query) {Number} [Y=join] Users unique value.
 * @apiParam (rest) {Object} a Users unique ID.
 * @apiParam (rest) {String} a.b=hello Users unique ID.
 * @apiParam (body) {Object} a Users unique ID.
 * @apiParam (body) {String} a.b=hello Users unique ID.
 * @apiParam (body) {String} a.b.c=world Users unique ID.
 * @apiParam (body) {String} a.c=ccccc Users unique ID.
 * @apiParamExample {json} Request-Example:
 *     {
 *       "id": 4711
 *     }
 *
 * @apiSuccess {String}   id            The Users-ID.
 * @apiSuccess {String}     registered    Registration String.
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError NoAccessRight Only authenticated Admins can access the data.
 * @apiError UserNotFound   The <code>id</code> of the User was not found.
 *
 * @apiErrorExample Response (example):
 *     HTTP/1.1 401 Not Authenticated
 *     {
 *       "error": "NoAccessRight"
 *     }
 */


/**
 * @api {post} /user Create a new User
 * @apiVersion 0.3.0
 * @apiName PostUser
 * @apiGroup User
 *
 * @apiDescription In this case "apiUse" is defined and used.
 * Define blocks with params that will be used in several functions, so you dont have to rewrite them.
 *
 * @apiParam {String} name Name of the User.
 *
 * @apiSuccess {String} id         The new Users-ID.
 *
 * @apiUse CreateUserError
 */


/**
 * @api {put} /user/:id Change a new User
 * @apiVersion 0.3.0
 * @apiName PutUser
 * @apiGroup User
 *
 * @apiDescription This function has same errors like POST /user, but errors not defined again, they were included with "apiUse"
 *
 * @apiParam {String} name Name of the User.
 *
 * @apiUse CreateUserError
 */

 

apidoc.json文件

{
  "name": "apidoc-example",
  "version": "0.3.0",
  "description": "apiDoc example project",
  "title": "Custom apiDoc browser title",
  "url" : "https://api.github.com/v1",
  
  "order": [
    "GetUser",
    "PostUser"
  ],
  "template": {
      "withCompare": true,
      "withGenerator": true
  }
}