apidoc利用代碼注釋書寫文檔

617035918 發布于2019-07-30 17:02 / 2769人閱讀

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

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

apidoc是一款利用源代碼中注釋來創建RESTful Web API文檔的工具。apidoc可用于C＃，Go，Dart，Java，JavaScript，PHP，TypeScript和所有其他支持Javadoc的語言。

安裝

npm install apidoc -g

運行

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

myapp/ 根據myapp文件夾下文件的注釋進行創建文檔

apidoc/ 文檔的輸出位置

mytemplate/ 使用的模板

命令行界面

查看幫助，用于顯示命令行參數：

apidoc -h

配置（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"
}

apidoc也支持通過package.json進行設置，只需在"apidoc":{}下添加參數即可。

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

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

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

使用

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

@api

@api {method} path [title]

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

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

eg:

/**
 * @api {get} /user/:id
 */

@apiDeprecated

@apiDeprecated [text]

將API方法標記為已棄用

名稱	描述
text	文字描述

apiDescription

@apiDescription text

API方法的詳細描述。

名稱	描述
text	文字描述

@apiName

@apiName name

定義方法文檔塊的名稱。名稱將用于生成的輸出中的子導航。結構定義不需要@apiName。

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

eg:

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

@apiGroup

@apiGroup name

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

名稱	描述
name	組的名稱。也用作導航標題。

eg:

/**
 * @api {get} /user/:id
 * @apiGroup User
 */

@apiHeader

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

描述API-Header傳遞的參數，例如用于授權。

名稱	描述
group	參數組別
type	參數類型
field	參數名
description	描述

eg:

/**
 * @api {get} /user/:id
 * @apiHeader {String} access-key Users unique access-key.
 */

@apiParam

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

用來描述API傳參值

名稱	描述
group	參數組別
type	參數類型
field	參數名
description	描述

eg:

 /** @apiParam (params) {int} time 時間戳(用于判斷請求是否超時)
   * @apiParam (params) {String} token 確認來訪者身份
   * @apiParam (params) {String} user_name 手機號或者郵箱
   * @apiParam (params) {String} user_pwd MD5加密的用戶密碼
   */

@apiSuccess

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

成功返回參數。用法和@apiParam類似。個人認為@apiSuccess有點多余，使用@apiSuccessExample就足夠了。

@apiSuccessExample

@apiSuccessExample [{type}] [title] example

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

eg:

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

@apiError

錯誤返回參數。用法和@apiSuccess類似

@apiErrorExample

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

@apiVersion

@apiVersion version

設置文檔塊的版本。版本也可用于@apiDefine。

eg:

/**
 * @api {get} /user/:id
 * @apiVersion 1.6.2
 */

@apiIgnore

@apiIgnore [hint]

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

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

eg:

/**
 * @apiIgnore Not finished Method
 * @api {get} /user/:id
 */

舉個栗子

來一個完整的例子

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

效果：

云服務器 GPU云服務器 html代碼書寫文檔注釋 java代碼書寫工具 js代碼書寫格式

文章版權歸作者所有，未經允許請勿轉載,若此文章存在違規行為，您可以聯系管理員刪除。

轉載請注明本文地址：http://specialneedsforspecialkids.com/yun/41971.html

apidoc利用代碼注釋書寫文檔

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

ChanceWong 2019-08-16 12:41 評論0 收藏0
apidoc利用代碼注釋書寫文檔

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

Awbeci 2019-07-01 10:16 評論0 收藏0
[原] Python 開發者面向文檔編程的正確姿勢

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

Y3G 2019-07-25 10:51 評論0 收藏0
利用apidoc維護api接口文檔

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

hiyayiji 2019-06-28 13:50 評論0 收藏0