成人国产在线小视频_日韩寡妇人妻调教在线播放_色成人www永久在线观看_2018国产精品久久_亚洲欧美高清在线30p_亚洲少妇综合一区_黄色在线播放国产_亚洲另类技巧小说校园_国产主播xx日韩_a级毛片在线免费

資訊專欄INFORMATION COLUMN

apidoc利用代碼注釋書寫文檔

ChanceWong / 2235人閱讀

摘要：個(gè)人博客同步文章是一款利用源代碼中注釋來創(chuàng)建文檔的工具。用法和類似錯(cuò)誤返回消息的示例，作為預(yù)格式化代碼輸出。設(shè)置文檔塊的版本。如果您在源代碼中留下過時(shí)或未完成的方法并且您不希望將其發(fā)布到文檔中，那么它很有用。

個(gè)人博客同步文章 https://mr-houzi.com/2018/07/...

apidoc是一款利用源代碼中注釋來創(chuàng)建RESTful Web API文檔的工具。apidoc可用于C＃，Go，Dart，Java，JavaScript，PHP，TypeScript和所有其他支持Javadoc的語言。
安裝 
npm install apidoc -g
運(yùn)行 
apidoc -i myapp/ -o apidoc/ -t mytemplate/

myapp/ 根據(jù)myapp文件夾下文件的注釋進(jìn)行創(chuàng)建文檔

apidoc/ 文檔的輸出位置

mytemplate/ 使用的模板

命令行界面

查看幫助，用于顯示命令行參數(shù)：

apidoc -h
配置（apidoc.json）

在apidoc.json配置項(xiàng)目的基本信息

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

apidoc也支持通過package.json進(jìn)行設(shè)置，只需在"apidoc":{}下添加參數(shù)即可。

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

如果你想設(shè)置header和footer，把下面信息加入到apidoc.json中（別忘記創(chuàng)建markdown文件）。

{
  "header": {
    "title": "My own header title",
    "filename": "header.md"
  },
  "footer": {
    "title": "My own footer title",
    "filename": "footer.md"
  }
}
使用

接下來給大家介紹一下常用的參數(shù)，完整介紹大家可以自己看一下官方文檔，正常情況來說下面這些就夠用。

@api 
@api {method} path [title]

聲明一下請求方法、請求路徑等。

名稱 描述
method 請求方法：DELETE，GET，POST，PUT，...
path 請求路徑
title 一個(gè)簡短的標(biāo)題。（用于導(dǎo)航和文章標(biāo)題）

eg:

/**
 * @api {get} /user/:id
 */
@apiDeprecated 
@apiDeprecated [text]

將API方法標(biāo)記為已棄用

名稱 描述
text 文字描述
apiDescription 
@apiDescription text

API方法的詳細(xì)描述。

名稱 描述
text 文字描述
@apiName 
@apiName name

定義方法文檔塊的名稱。名稱將用于生成的輸出中的子導(dǎo)航。結(jié)構(gòu)定義不需要@apiName。

名稱 描述
name 方法的唯一名稱。
格式：方法 + 路徑（例如Get + User），建議以這種方式命名

eg:

/**
 * @api {get} /user/:id
 * @apiName GetUser
 */
@apiGroup 
@apiGroup name

定義方法文檔塊屬于哪個(gè)組。組將用于生成的輸出中的主導(dǎo)航。例如：login和register接口都可以劃分到User組。

名稱 描述
name 組的名稱。也用作導(dǎo)航標(biāo)題。

eg:

/**
 * @api {get} /user/:id
 * @apiGroup User
 */
@apiHeader 
@apiHeader [(group)] [{type}] [field=defaultValue] [description]

描述API-Header傳遞的參數(shù)，例如用于授權(quán)。

名稱 描述
group 參數(shù)組別
type 參數(shù)類型
field 參數(shù)名
description 描述

eg:

/**
 * @api {get} /user/:id
 * @apiHeader {String} access-key Users unique access-key.
 */
@apiParam 
@apiParam [(group)] [{type}] [field=defaultValue] [description]

用來描述API傳參值

名稱 描述
group 參數(shù)組別
type 參數(shù)類型
field 參數(shù)名
description 描述

eg:

 /** @apiParam (params) {int} time 時(shí)間戳(用于判斷請求是否超時(shí))
   * @apiParam (params) {String} token 確認(rèn)來訪者身份
   * @apiParam (params) {String} user_name 手機(jī)號(hào)或者郵箱
   * @apiParam (params) {String} user_pwd MD5加密的用戶密碼
   */
@apiSuccess 
@apiSuccess [(group)] [{type}] field [description]

成功返回參數(shù)。用法和@apiParam類似。個(gè)人認(rèn)為@apiSuccess有點(diǎn)多余，使用@apiSuccessExample就足夠了。

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

成功返回消息的示例，作為預(yù)格式化代碼輸出。

eg:

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

錯(cuò)誤返回參數(shù)。用法和@apiSuccess類似

@apiErrorExample

錯(cuò)誤返回消息的示例，作為預(yù)格式化代碼輸出。用法和@apiSuccessExample類似。

@apiVersion 
@apiVersion version

設(shè)置文檔塊的版本。版本也可用于@apiDefine。

eg:

/**
 * @api {get} /user/:id
 * @apiVersion 1.6.2
 */
@apiIgnore 
@apiIgnore [hint]

將它放在一個(gè)塊的頂部。
@apiIgnore將無法解析塊。如果您在源代碼中留下過時(shí)或未完成的方法并且您不希望將其發(fā)布到文檔中，那么它很有用。

名稱 描述
hint 用于提示為什么忽略這個(gè)塊。

eg:

/**
 * @apiIgnore Not finished Method
 * @api {get} /user/:id
 */
舉個(gè)栗子

來一個(gè)完整的例子

/**
 * @api {post} /user/login 用戶登錄
 * @apiName login
 * @apiGroup User
 * @apiParam (params) {int} time 時(shí)間戳(用于判斷請求是否超時(shí))
 * @apiParam (params) {String} token 確認(rèn)來訪者身份
 * @apiParam (params) {String} user_name 手機(jī)號(hào)或者郵箱
 * @apiParam (params) {String} user_pwd MD5加密的用戶密碼
 * @apiSuccessExample Success-Response:
 *  {
 *      "code": 200,
 *      "msg": "登錄成功！",
 *      "data": {
 *           "uid": 1, //用戶ID
 *           "user_phone": "13011111111", //用戶手機(jī)號(hào)
 *           "user_nickname": "小明", //用戶昵稱
 *           "user_email": "[email protected]", //用戶郵箱
 *           "user_rtime": 1501414343 //用戶注冊時(shí)間
 *  }
 *
 */

效果：

文章版權(quán)歸作者所有，未經(jīng)允許請勿轉(zhuǎn)載,若此文章存在違規(guī)行為，您可以聯(lián)系管理員刪除。

轉(zhuǎn)載請注明本文地址：http://systransis.cn/yun/71537.html

相關(guān)文章

  • apidoc利用代碼注釋書寫文檔

    摘要：個(gè)人博客同步文章是一款利用源代碼中注釋來創(chuàng)建文檔的工具。用法和類似錯(cuò)誤返回消息的示例，作為預(yù)格式化代碼輸出。設(shè)置文檔塊的版本。如果您在源代碼中留下過時(shí)或未完成的方法并且您不希望將其發(fā)布到文檔中，那么它很有用。 個(gè)人博客同步文章 https://mr-houzi.com/2018/07/... apidoc是一款利用源代碼中注釋來創(chuàng)建RESTful Web API文檔的工具。apido...

    617035918 評(píng)論0 收藏0

  • apidoc利用代碼注釋書寫文檔

    摘要：個(gè)人博客同步文章是一款利用源代碼中注釋來創(chuàng)建文檔的工具。用法和類似錯(cuò)誤返回消息的示例，作為預(yù)格式化代碼輸出。設(shè)置文檔塊的版本。如果您在源代碼中留下過時(shí)或未完成的方法并且您不希望將其發(fā)布到文檔中，那么它很有用。 個(gè)人博客同步文章 https://mr-houzi.com/2018/07/... apidoc是一款利用源代碼中注釋來創(chuàng)建RESTful Web API文檔的工具。apido...

    Awbeci 評(píng)論0 收藏0

  • [原] Python 開發(fā)者面向文檔編程的正確姿勢

    摘要：用注釋寫單元測試單元測試是代碼開發(fā)環(huán)節(jié)必不可少的一環(huán)，對(duì)于定位和代碼質(zhì)量而言是非常重要的。現(xiàn)在最廣為人知的單元測試框架就是，它借鑒了中成熟的單元測試框架的。 概述 showImg(https://segmentfault.com/img/bVD66s?w=550&h=550); 秦人不暇自哀,而后人哀之;后人哀之而不鑒之,亦使后人而復(fù)哀后人也! --論面向文檔編程的重要性 如果想看見識(shí)...

    Y3G 評(píng)論0 收藏0

  • 利用apidoc維護(hù)api接口文檔

    摘要：什么是是一個(gè)輕量級(jí)的在線接口文檔生成系統(tǒng)，支持多種主流語言，包括和等。使用者按照要求書寫相關(guān)注釋，就可以生成可讀性好界面美觀的在線接口文檔。雙擊文件夾下的，就能看到文檔了。 什么是apidoc apidoc是一個(gè)輕量級(jí)的在線REST接口文檔生成系統(tǒng)，支持多種主流語言，包括Java、C、C#、PHP和Javascript等。使用者按照要求書寫相關(guān)注釋，就可以生成可讀性好、界面美觀的在線接...

    hiyayiji 評(píng)論0 收藏0

發(fā)表評(píng)論

0條評(píng)論

最新活動(dòng)
閱讀需要支付1元查看
<