springboot系列：SpringBoot第十二篇：springboot集成apidoc

首先聲明下，apidoc是基于注釋來生成文檔的，它不基于任何框架，而且支持大多數編程語言，為了Springboot系列的完整性，所以標了個題。

一、apidoc簡介

apidoc通過在你代碼的注釋來生成api文檔的。它對代碼沒有侵入性，只需要你寫好相關的注釋即可，并且它僅通過寫簡單的配置就可以生成高顏值的api接口頁面。它基于node.js，所以你需要安裝node.js環境。node.js安裝，點擊這里。這里就不介紹。

二、準備工作

安裝完node.js安裝api.doc,它的項目源碼：https://github.com/apidoc/apidoc?。

通過命令安裝：

npm install apidoc -g

三、注釋怎么寫

·??????@api

@api?{method}?path?[title]

method：請求方法，

path：請求路徑

title(可選)：標題

·??????@apiDescription

@apiDescription?text

text說明

·??????@apiError

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

（group）（可選）：參數將以這個名稱分組，不設置的話，默認是Error?4xx

{type}（可選）：返回值類型，例如：{Boolean},?{Number},?{String},?{Object},?{String[]}

field：返回值字段名稱

descriptionoptional（可選）：返回值字段說明

·??????@apiGroup

@apiGroup?name

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

更多注釋，參見官方文檔：http://apidocjs.com/#params

四、寫給栗子

首先寫配置文件

在項目的主目錄新建一個apidoc.json文件：

{

"name":?"example",

"version":?"0.1.0",

"description":?"A?basic?apiDoc?example"

}

更多配置參考：http://apidocjs.com/#configuration

寫個注釋:

/**

*?@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":"注冊成功"}

*/

用apidoc命令生成文檔界面

先cd到工程的外層目錄，并在外層目建個輸出文檔的目錄，我建的是docapi。

輸命令：

apidoc -i chapter4/ -o apidoc/

-i?輸入目錄-o?輸出目錄

chapter4是我的工程名。

可以看到在apidoc目錄生成了很多文件:

打開index.html,可以看到文檔頁面:

五、參考資料

apidoc

apidocjs.com

使用apidoc?生成Restful web Api文檔

方志朋簡介：SpringCloud中國社區聯合創始人，博客訪問量突破一千萬，愛好開源，熱愛分享，活躍于各大社區，保持著非常強的學習驅動力，終身學習踐行者，終身學習受益者。目前就職于國內某家知名互聯網保險公司，擔任DEVOPS工程師，對微服務領域和持續集成領域研究較深，精通微服務框架SpringCloud

Spring Boot JavaScript

版權聲明：本文內容由網絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發現本站中有涉嫌抄襲或描述失實的內容，請聯系我們jiasou666@gmail.com 處理，核實后本網站將在24小時內刪除侵權內容。