2. 程式人生 > >使用apidoc 生成Restful web Api文件

使用apidoc 生成Restful web Api文件

阿新 • • 發佈：2018-11-15

在專案開發過程中，總會牽扯到介面文件的設計與編寫，之前使用的都是office工具，寫一個文件，總也是不夠漂亮和直觀。好在git上的開源大神提供了生成文件的工具，so來介紹一下！
該工具是Nodejs的模組，請務必在使用前安裝好nodejs環境！

工具名稱：apiDoc
Git地址：https://github.com/apidoc/apidoc
專案地址：http://apidocjs.com/
樣例專案：http://apidocjs.com/example_basic/
apoDoc是從原始碼的註釋中生成RestFul api 文件，樣子還是蠻漂亮的……

自己寫了的ApiDoc文件自動生成工具，避免每次寫完後手動執行生成程式碼

http://blog.csdn.net/soslinken/article/details/50476384

支援的註釋樣式:
JavaDoc-Style

/**
 * This is a comment.
 */

CoffeeScript

###
This is a comment.
###

Elixir

@apidoc """
This is a comment.
"""

Erlang（%不是必須的）

%{
% This is a comment.
%}

Perl (Doxygen)

#**
# This is a comment.
#*

Python

"""
This is a comment.
"""

Ruby

=begin
This is a comment.
=end

安裝apiDoc

npm install apidoc -g

使用npm命令安裝apidoc即可！

使用方式:
在命令列中輸入

apidoc -f ".*\\.js$" -f ".*\\.java$" -i myapp/ -o apidoc/ -t mytemplate/

引數說明：
-f 檔案過濾
使用正則表示式，表示哪些檔案需要本轉換，不設定的情況下，預設為.cs .dart .erl .go .java .js .php .py .rb .ts 字尾的檔案。

-i 程式碼資料夾

-o 輸出Api文件的路徑

-t 使用模板檔案的路徑，可以自定義輸出的模板

常用的命令格式如下:

apidoc -i myapp/ -o apidoc/

配置
無package.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檔案時，在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"
  }
}

配置屬性如下:
name：專案名稱
version：專案版本
description：專案介紹
title：瀏覽器顯示的標題內容
url：endpoints的字首，例如https://api.github.com/v1
sampleUrl：如果設定了，則在api文件中出現一個測試用的from表單
header
title：導航文字包含header.md檔案
filename：markdown-file 檔名
footer
title：導航文字包含header.md檔案
filename：markdown-file 檔名
order：用於配置輸出 api-names/group-names 排序，在列表中的將按照列表中的順序排序，不在列表中的名稱將自動顯示。

模板的配置:
在apidoc.json中或在package.json中新增template屬性，將對模板進行特殊設定
forceLanguage：生成指定語言的文件，簡體中文僅需設定”zh-cn”，支援的語言：https://github.com/apidoc/apidoc/tree/master/template/locales
withCompare：是否啟用與舊版本的比較功能，預設為true
withGenerator：是否輸出生成資訊，預設為true
jQueryAjaxSetup：設定Ajax請求的預設值,參見http://api.jquery.com/jquery.ajaxsetup/

我使用的配置如下:

{
  "name": "測試",
  "version": "0.0.1",
  "description": "API文件測試",
  "title": "API文件測試",
  "url" : "http://xxxxxxx",
  "sampleUrl" : "http://xxxxxxxx",
  "template":{
    "forceLanguage":"zh-cn"
  }
}

先來個demo試試：
在myapp資料夾下建立example.java

/**
 * @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.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

之後執行

apidoc -i myapp/ -o apidoc/

開啟apidoc資料夾下的index.html即可看到效果。贊贊噠……

重頭戲來了，下面要講解一下apiDoc的註釋都是什麼含義

@api

@api {method} path [title]

使用該註釋的才能被識別成為文件的一塊內容

method：請求方法，參見https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods
path：請求路徑
title(可選)：標題

Example:

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

@apiDefine

@apiDefine name [title]
                     [description]

定義重複內容，供其他模組引用

name：重複模組名
title（可選）：標題
description（可選）：說明

Example1:

/**
 * @apiDefine MyError
 * @apiError UserNotFound The <code>id</code> of the User was not found.
 */

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

Example2:

/**
 * @apiDefine admin User access only
 * This optional description belong to to the group admin.
 */

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

@apiDescription

@apiDescription text

設定多行說明

text：多行說明內容

Example

/**
 * @apiDescription This is the Description.
 * It is multiline capable.
 *
 * Last line of Description.
 */

@apiError

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

請求錯誤引數

（group）（可選）：引數將以這個名稱分組，不設定的話，預設是Error 4xx
{type}（可選）：返回值型別，例如：{Boolean}, {Number}, {String}, {Object}, {String[]}
field：返回值欄位名稱
descriptionoptional（可選）：返回值欄位說明

Example:

/**
 * @api {get} /user/:id
 * @apiError UserNotFound The <code>id</code> of the User was not found.
 */

@apiErrorExample

@apiErrorExample [{type}] [title]
                 example

錯誤返回資訊樣例。

type（可選）：返回內容的格式
title（可選）：標題
example：樣例，可以是多行文字

Example:

/**
 * @api {get} /user/:id
 * @apiErrorExample {json} Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

@apiExample

@apiExample [{type}] title
            example

請求Api的測試樣例

{type}（可選）：請求方式型別
title：標題
example：樣例，可以是多行文字

Example:

/**
 * @api {get} /user/:id
 * @apiExample {curl} Example usage:
 *     curl -i http://localhost/user/4711
 */

@apiGroup

@apiGroup name

定義Api的分組

name：組名稱，也是導航的標題

Example:

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

@apiHeader

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

定義head引數

(group)（可選）：分組
{type}（可選）：型別，例如：{Boolean}, {Number}, {String}, {Object}, {String[]}
field：變數名
[field]：定義變數，並標記變數是可選項
=defaultValue（可選）：預設值
description（optional）：變數說明

Examples:

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

@apiHeaderExample

@apiHeaderExample [{type}] [title]
                   example

head引數樣例

{type}（可選）：請求方式型別
title：標題
example：樣例，可以是多行文字

Example:

/**
 * @api {get} /user/:id
 * @apiHeaderExample {json} Header-Example:
 *     {
 *       "Accept-Encoding": "Accept-Encoding: gzip, deflate"
 *     }
 */

@apiIgnore

@apiIgnore [hint]

忽略不釋出到文件

hint（可選）：不釋出的原因

Example:

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

@apiName

@apiName name

定義api名稱

name：api名稱

Example:

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

@apiParam

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

定義請求Api的引數

(group)（可選）：分組
{type}（可選）：型別，例如：{Boolean}, {Number}, {String}, {Object}, {String[]}
{type{size}}（可選）：型別限定長度，例如：{string{..5}} 限定最大長度為5個字元
{string{2..5}} 限定最短2個字元，最長5個字元
{number{100-999}} 限定數字在100-999之間
{type=allowedValues}（可選）：型別限定值，例如：{string=”small”}限定只允許傳遞small字元，
{string=”small”,”huge”} 限定只允許傳遞small或huge字元，
{number=1,2,3,99} 限定只允許傳1，2，3，99這四個數字
field：變數名
[field]：定義變數，並標記變數是可選項
=defaultValue（可選）：預設值
description（optional）：變數說明

Examples:

/**
 * @api {get} /user/:id
 * @apiParam {Number} id Users unique ID.
 */

/**
 * @api {post} /user/
 * @apiParam {String} [firstname]  Optional Firstname of the User.
 * @apiParam {String} lastname     Mandatory Lastname.
 * @apiParam {String} country="DE" Mandatory with default value "DE".
 * @apiParam {Number} [age=18]     Optional Age with default 18.
 *
 * @apiParam (Login) {String} pass Only logged in users can post this.
 *                                 In generated documentation a separate
 *                                 "Login" Block will be generated.
 */

@apiParamExample

@apiParamExample [{type}] [title]
                   example

請求引數樣例

{type}（可選）：請求方式型別
title：標題
example：樣例，可以是多行文字

Example:

/**
 * @api {get} /user/:id
 * @apiParamExample {json} Request-Example:
 *     {
 *       "id": 4711
 *     }
 */

@apiPermission

@apiPermission name

定義介面許可權

name：許可權名稱

Example:

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

@apiSampleRequest

@apiSampleRequest url
  
    
   
  • 1
    •

設定測試請求form，如果在apidoc.json或package.json中設定過了sampleUrl，則預設請求地址為，sampleUrl+apipath，設定這個標籤則重寫測試請求路徑

url：測試地址，
樣例
@apiSampleRequest http://www.example.com 改變測試地址
@apiSampleRequest /my_test_path 在apipath中加字首
@apiSampleRequest off 不顯示測試請求from

Examples:
預設請求的地址是http://api.github.com/user/:id

Configuration parameter sampleUrl: "http://api.github.com"
/**
 * @api {get} /user/:id
 */

需要將測試地址修改為http://test.github.com/some_path/user/:id，則

Configuration parameter sampleUrl: "http://api.github.com"
/**
 * @api {get} /user/:id
 * @apiSampleRequest http://test.github.com/some_path/
 */

當地址需要請求http://api.github.com/test/user/:id則

Configuration parameter sampleUrl: "http://api.github.com"
/**
 * @api {get} /user/:id
 * @apiSampleRequest /test
 */

不需要測試請求from

Configuration parameter sampleUrl: "http://api.github.com"
/**
 * @api {get} /user/:id
 * @apiSampleRequest off
 */

沒有設定sampleUrl時需要顯示測試請求from，並設定請求http://api.github.com/some_path/user/:id

Configuration parameter sampleUrl is not set
/**
 * @api {get} /user/:id
 * @apiSampleRequest http://api.github.com/some_path/
 */

@apiSuccess

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

請求成功返回的引數

（group）（可選）：引數將以這個名稱分組，不設定的話，預設是Error 4xx
{type}（可選）：返回值型別，例如：{Boolean}, {Number}, {String}, {Object}, {String[]}
field：返回值欄位名稱
descriptionoptional（可選）：返回值欄位說明

Example:

/**
 * @api {get} /user/:id
 * @apiSuccess (200) {String} firstname Firstname of the User.
 * @apiSuccess (200) {String} lastname  Lastname of the User.
 */

@apiSuccessExample

@apiSuccessExample [{type}] [title]
                   example

請求成功返回資料樣例

{type}（可選）：請求方式型別
title：標題
example：樣例，可以是多行文字

Example:

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

@apiUse

@apiUse name

使用在@apiDefine中定義的內容

name：在@apiDefine定義的name

Example:

/**
 * @apiDefine MySuccess
 * @apiSuccess {string} firstname The users firstname.
 * @apiSuccess {number} age The users age.
 */

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

@apiVersion

@apiVersion version

設定Api的版本號

version：版本號，格式(major.minor.patch)

Example:

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

以上就是apiDoc的介紹！謝謝各位看官……

附上一個樣例

user.java

/**
 * @api {POST} /register 註冊使用者
 * @apiGroup Users
 * @apiVersion 0.0.1
 * @apiDescription 用於註冊使用者
 * @apiParam {String} account 使用者賬戶名 
 * @apiParam {String} password 密碼
 * @apiParam {String} mobile 手機號
 * @apiParam {int} vip = 0  是否註冊Vip身份 0 普通使用者 1 Vip使用者
 * @apiParam {String} [recommend] 邀請碼
 * @apiParamExample {json} 請求樣例：
 *                ?account=sodlinken&password=11223344&mobile=13739554137&vip=0&recommend=
 * @apiSuccess (200) {String} msg 資訊
 * @apiSuccess (200) {int} code 0 代表無錯誤 1代表有錯誤
 * @apiSuccessExample {json} 返回樣例:
 *                {"code":"0","msg":"註冊成功"}
 */

 /**
 * @api {POST} /login 使用者登入
 * @apiGroup Users
 * @apiVersion 0.0.1
 * @apiDescription 用於使用者登入
 * @apiParam {String} userName 使用者名稱
 * @apiParam {String} password 密碼
 * @apiParamExample {json} 請求樣例：
 *                ?userName=張三&password=11223344
 * @apiSuccess (200) {String} msg 資訊
 * @apiSuccess (200) {String} code 0 代表無錯誤 1代表有錯誤
 * @apiSuccess (200) {String} user 使用者資訊
 * @apiSuccess (200) {String} userId 使用者id
 * @apiSuccessExample {json} 返回樣例:
 *                {"code":"0","msg":"登入成功","userId":"fe6386d550bd434b8cd994b58c3f8075"}
 */

 /**
 * @api {GET} /users/:id 獲取使用者資訊
 * @apiGroup Users
 * @apiVersion 0.0.1
 * @apiDescription 獲取使用者資訊
 * @apiSuccess (200) {String} msg 資訊
 * @apiSuccess (200) {int} code 0 代表無錯誤 1代表有錯誤
 * @apiSuccess (200) {String} name 真實姓名
 * @apiSuccess (200) {String} mobile 手機號
 * @apiSuccess (200) {String} birthday 生日
 * @apiSuccess (200) {String} email 郵箱
 * @apiSuccess (200) {String} summary 簡介
 * @apiSuccess (200) {String} recommendCode 我的推薦碼
 * @apiSuccess (200) {String} idCardNo 身份證號
 * @apiSuccess (200) {String} memberState 會員狀態 0普通使用者 1VIP 2賬戶凍結
 * @apiSuccess (200) {String} address 家庭住址 
 * @apiSuccess (200) {String} money 賬戶現金
 * @apiSuccessExample {json} 返回樣例:
 * {
 *   "code": 0,
 *   "msg": "",
 *   "name": "真實姓名",
 *   "mobile": 15808544477,
 *   "birthday": "1990-03-05",
 *   "email": "slocn@gamil.com",
 *   "summary": "簡介",
 *   "recommendCode": "我的推薦碼",
 *   "idCardNo": "身份證號",
 *   "memberState": 1,
 *   "address": "家庭住址",
 *   "money": "30.65"
 * }
 */


 /**
 * @api {POST} /users/:id 修改(完善)使用者資訊
 * @apiGroup Users
 * @apiVersion 0.0.1
 * @apiDescription 修改(完善)使用者資訊
 * @apiParam (200) {String} [name] 真實姓名
 * @apiParam (200) {String} [mobile] 手機號
 * @apiParam (200) {String} [birthday] 生日
 * @apiParam (200) {String} [email] 郵箱
 * @apiParam (200) {String} [summary] 簡介
 * @apiParam (200) {String} [idCardNo] 身份證號
 * @apiParam (200) {String} [address] 家庭住址
 * @apiSuccess (200) {String} msg 資訊
 * @apiSuccess (200) {int} code 0 代表無錯誤 1代表有錯誤
 * @apiSuccessExample {json} 返回樣例:
 *                {"code":"0","msg":"修改成功"}
 */

這個樣例可以直接生成，生成後即可看到apidoc的效果

2018年1月22日 更新

看到有很多人說中文亂碼的事情，今天特別更新說明一下

主要是 @apiGroup 不支援utf-8 字串。僅支援ascii碼。所以很多使用者要麼只能用英文說明，要麼就放棄這個工具。

在官方有個辦法可以實現utf-8字串放置在@apiGoup 中。
程式碼如下

/**
 * @apiDefine userApiStr 使用者介面文件 
 */

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup userApiStr
*/

說明
1、@apiDefine 必須放置在 /* …../中，也必須與引用變數的地方分開。
2、@apiGroup 後 放置的是 @apiDefine 定義的 變數名

其實本質上是定義了一個引用變數，這個變數支援utf-8。

相關推薦

使用apidoc 生成Restful web Api文件

在專案開發過程中，總會牽扯到介面文件的設計與編寫，之前使用的都是office工具，寫一個文件，總也是不夠漂亮和直觀。好在git上的開源大神提供了生成文件的工具，so來介紹一下！ 該工具是Nodejs的模組，請務必在使用前安裝好nodejs環境！ 工具名稱：apiDoc Git地址：http

介面文件自動生成、使用apidoc 生成Restful web Api文件（express）

專案地址為： 專案地址 這個是自動生成網頁，我們就可以擺脫excel。 一.首先是使用node安裝apiDoc npm install apidoc -g 二.在需要生成介面的添加註釋 /** * @api {post} /v1/login

SpringBoot中使用Swagger生成RestFul規範API文件

j簡單介紹Swagger的作用: Swagger是為了描述一套標準的而且是和語言無關的REST API的規範。對於外部呼叫者來說，只需通過Swagger文件即可清楚Server端提供的服務，而不需去閱讀原始碼或介面文件說明。 官方網站為：http://swagger.io 中文網站：http

SpringBoot(二十)Swagger2-自動生成RESTful規範API文件

  Swagger2 方式，一定會讓你有不一樣的開發體驗：功能豐富 ：支援多種註解，自動生成介面文件介面，支援在介面測試API介面功能；及時更新 ：開發過程中花一點寫註釋的時間，就可以及時的更新API文件，省心省力；整合簡單 ：通過新增pom依賴和簡單配置，內嵌於應用中就可同時釋

nodejs restful 的api文件生成

1、apidoc的官網 http://apidocjs.com   2、安裝nodejs環境，安裝apidoc  npm install apidoc -g   3、在專案根目錄建立：apidoc.json；如： { 　　"name": "

用VSCode開發一個asp.net core2.0+angular5項目(5): Angular5+asp.net core 2.0 web api文件上傳

owb bus sed loaded runt ace created one 做了 第一部分: http://www.cnblogs.com/cgzl/p/8478993.html 第二部分: http://www.cnblogs.com/cgzl/p/8481825.

web api 文件 html css js

Web API Web API介紹 API的概念 API（Application Programming Interface,應用程式程式設計介面）是一些預先定義的函式，目的是提供應用程式與開發人員基於某軟體或硬體得以訪問一組例程的能力，而又無需訪

Java小技巧自動生成註釋、api文件

cmd 命令 javadoc的使用 win+R彈出執行視窗 輸入cmd回車，進入dos介面，輸入java -version，檢查java是否配置好。如下圖所示 配置好java後，我們新建一個含有公共類的java檔案，在裡面寫點東西。 然後儲存到資料夾test裡面

使用springfox-staticdocs生成swagger離線api文件附帶原始碼

使用springfox-staticdocs生成swagger離線api 因為最近公司部分專案使用swagger來管理線上介面，但在某些場景下需要提供離線的api文件。因此在網上參考了一些部落格以後寫了一個小專案，只需要配置對應的url，既可生成離線的a

Maven學習總結（43）——利用javadoc外掛生成專案的API文件

在進行Java學習的時候，相信大家都看過線上或者下載的java api文件，可能是html格式或者chm格式的，其實這些參考文件也是很容易生成的，這裡介紹一個maven的外掛來實現專案程式碼文件的生成。

使用swaggo自動生成Restful API文件

Java使用Spring Boot寫Restful API時，可以在程式碼裡用註解來標識API，編譯為Jar包後，執行時Web應用可以直接託管API文件。具體的可以參考這篇文章：使用swagger來做API文件。 那麼golang繫有沒有類似的做法呢？ 有是有的，只是沒有springfox的那麼方便就是了

apidoc 自動生成api文件

下載node.js 安裝 安裝npm淘寶映象 安裝apidoc 專案應用目錄目錄下新建apidoc.json檔案，例如tp的application目錄 { "name": "JD SHOP Api", "version": "1.0.0", "descriptio

在.net core web api專案中安裝swagger展示api介面（相當於生成api文件）

1，  建立或開啟專案後，在“程式包管理器控制檯”中執行以下命令新增包引用： Install-Package Swashbuckle.AspNetCore   2，在專案中開啟Startup.cs檔案,找到 Configure 方法，在其中新增如下程式碼：  app.Us

Web Api 2.0中使用Swagger生成Api文件的2個小Tips

當Web Api 2.0使用OAuth2授權時，如何在Swagger中新增Authorization請求頭？ Swagger說明文件支援手動呼叫Api, 但是當Api使用OAuth2授權時，由於沒有地方可以輸入授權Token, 導致響應結果一直是401沒有授權。

在Spring中使用Springfox和swagger生成restful風格的API文件

發現一位博主寫的特別棒 強烈推薦參考他的：大牛的網址 由於Spring Boot能夠快速開發、便捷部署等特性，相信有很大一部分Spring Boot的使用者會用來構建RESTful API。而我們構建RESTful API的目的通常都是由於多終端的原因，這些

使用swagger2markup和asciidoctor生成美觀的Restful API文件

    目前，大家通常都是用Swagger來編寫Rest API文件，使用Swagger註解和Springfox，可以方便的從原始碼生成文件，保持文件和原始碼一致。使用Swagger-ui工具，介面的消費方可以檢視介面定義並從瀏覽器直接呼叫介面。如何實現Swagger和Spr

初次嘗試swagger springmvc整合 生成restful api文件

1、maven 所需jar包 <dependency>         <groupId>com.mangofactory</groupId>         <artifactId>swagger-springmvc<

swagger2 離線文件 文件中心搭建 json swagger 自動生成api文件

最近找了一個自動生成api文件的工具swagger，相對swaggerEdit就不說了。個人比較懶，還是自動生成來的便捷，尤其是老專案，新專案在初期可能會維護，但是到了後期就很難保證了。所以，那些需要一些特殊配置說明的文件工具就不提了。 這篇文章主要是在swagger2 swagger UI的基

Laravel（PHP）使用Swagger生成API文件不完全指南 - 基本概念和環境搭建 - 簡書

在PHPer中，很多人聽說過Swagger，部分人知道Swagger是用來做API文件的，然而只有少數人真正知道怎麼正確使用Swagger，因為PHP界和Swagger相關的資料實在是太少了。所以鄙人斗膽一試，希望能以本文幫助到大家瞭解Swagger，從此告別成天用Word、Markdown折騰API文件的日

Swagger2構建強大的RESTful API文件實戰

一 點睛 RESTful API的重磅好夥伴Swagger2，它可以輕鬆的整合到Spring Boot中，並與Spring MVC程式配合組織出強大RESTful API文件。它既可以減少我們建立文件的工作量，同時說明內容又整合入實現程式碼中，讓維護文件和修改程式碼整合為一體，可以