apidoc guide with nodejs
1 like452 views
1. The document introduces how to configure and write API documentation using APIDOC. 2. It describes setting up configuration files and covers common configuration parameters. 3. Examples are provided on how to document APIs using documentation tags to describe versions, parameters, errors, responses and more.
![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"
}](https://image.slidesharecdn.com/getting-started-with-apidoc-160718055501/85/apidoc-guide-with-nodejs-4-320.jpg)
![API ⽂件撰寫
參數列表
/
O @api API @api {method} path [title]
@apiDescription API @apiDescription text
@apiDefine API @apiUse @apiDefine name [title] [description]
@apiUse @apiDefine @apiUse @apiDefineName
@apiError
API 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
@apiSuccess
API group
@apiSuccess
group = Success 200
@apiSuccess [(group)] [{type}] field
[description]
@apiSuccessExample @apiSuccess
@apiSuccessExample [{type}] {title}
example
@apiPermission API @apiPermission name](https://image.slidesharecdn.com/getting-started-with-apidoc-160718055501/85/apidoc-guide-with-nodejs-5-320.jpg)
apidoc guide with nodejs
- 2. 初次使⽤ 3............................................................... Node.js 設定 3...................................................................................................................... 兩個設定檔的相同處 3......................................................................................................... apidoc.json 參數 4.................................................. 參數列表 4............................................................................................................................ 範例 4................................................................................................................................... API ⽂件撰寫 5........................................................ 參數列表 5............................................................................................................................ APIDOC 撰寫範例 6.............................................................................................................
- 3. 初次使⽤ 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" } }
- 4. 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" }
- 5. API ⽂件撰寫 參數列表 / O @api API @api {method} path [title] @apiDescription API @apiDescription text @apiDefine API @apiUse @apiDefine name [title] [description] @apiUse @apiDefine @apiUse @apiDefineName @apiError API 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 @apiSuccess API group @apiSuccess group = Success 200 @apiSuccess [(group)] [{type}] field [description] @apiSuccessExample @apiSuccess @apiSuccessExample [{type}] {title} example @apiPermission API @apiPermission name
- 6. 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": "" * } */