那些年⼀起追的APIDOC APIDOC 使⽤⼿冊

Ivan Wei

第⼀版

初次使⽤ 3 ...............................................................Node.js 設定 3 ......................................................................................................................

兩個設定檔的相同處 3 .........................................................................................................

apidoc.json 參數 4 ..................................................參數列表 4 ............................................................................................................................

範例 4 ...................................................................................................................................

API ⽂件撰寫 5 ........................................................參數列表 5 ............................................................................................................................

APIDOC 撰寫範例 6.............................................................................................................

初次使⽤ Node.js 設定 兩個地⽅可以放設定資料

1. 在根⽬錄新增「apidoc.json」

2. package.json 新增「apidoc: {}」

設定內容有重覆，系統會以 apidoc.json 為主。

兩個設定檔的相同處

apidoc.json package.json

{ "name": "example", "version": "0.1.0", "description": "apiDoc basic example", "title": "Custom apiDoc browser title", "url" : "https://api.github.com/v1" }

{ "name": "example", "version": "0.1.0", "description": "apiDoc basic example", "apidoc": { "title": "Custom apiDoc browser title", "url" : "https://api.github.com/v1" }}

apidoc.json 參數 參數列表

範例

( )

name String ( "name" )

version String ( "0.0.0" )

description String ( "description" )

title String ( "title" )

url String ( "http://localhost" ) Hostname

sampleUrl String ( "http://api.chocolabs.com" ) Hostname

header Object ( "title": "This header", "filename": "header.md" )

Header

footer Object ( "title": "This header", "filename": "header.md" )

Footer

order Array ( [“A”, “B”, "C"] ) API name / Group name

"name": "Project-Name","version": "3.0.1","description": " ","apidoc": { "title": "Demo API Docs", "url": "https://api.github.com/v1", "sampleUrl": "http://localhost"}

API ⽂件撰寫 參數列表

/

O @api API @api {method} path [title]

@apiDescription API @apiDescription text

@apiDefine API @apiUse @apiDefine name [title] [description]

@apiUse @apiDefine @apiUse @apiDefineName

@apiErrorAPI  group

@apiError group = Error 4XX

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

@apiErrorExample @apiError @apiErrorExample [{type}] [title] example

@apiExample API curl API @apiExample [{type}] title example

O @apiGroup API @apiGroup name

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

@apiHeaderExample @apiHeader @apiHeaderExample [{type}] [title] example

@apiIgnore API @apiIgnore [hint]

O @apiName API @apiName name

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

@apiParamExample @apiParam @apiParamExample [{type}] [title] example

@apiSampleRequest API @apiSampleRequest url

@apiSuccessAPI group

@apiSuccess group = Success 200

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

@apiSuccessExample @apiSuccess @apiSuccessExample [{type}] {title} example

@apiPermission API @apiPermission name

1. @apiDefine API

2. API O

3.

APIDOC 撰寫範例

@apiVersion API @apiVersion version

/

/** * @apiDefine demoDefine * @apiDescription This is a demo. *//** * @apiUse demoDefine → @apiDefine demoDefine * @api {get} /info/:Id * @apiVersion 0.0.1 * @apiName info * @apiGroup Demo * * @apiParam {String} UUID * * @apiError (403) {json} DemoError * @apiErrorExample DemoError: * HTTP/1.1 403 Forbidden * { * "message": “Failed.” * } * * @apiSuccessExample Success: * HTTP/1.1 200 OK * { * "info" : {...}, * "total" : "", * } * * @apiSuccessExample Success: * HTTP/1.1 200 OK * { * "info": {...}, * "total": "", * "current": "" * } */