在老大的指引下，需要将系統的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檔案
一個靜态的文檔很漂亮的生成了，但是實際控制這個現實的是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設計到如下的參數
（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
}
} 文中有錯誤的地方希望指出，共同進步