在開發(fā)接口的過(guò)程中，需要向外發(fā)布相應(yīng)的接口文檔。開始的時(shí)候使用word來(lái)寫文檔，時(shí)間長(zhǎng)了發(fā)現(xiàn)有幾個(gè)問題。1) 編寫不方便。每次新增借口的時(shí)候都要復(fù)制上一個(gè)接口，然后再進(jìn)行修改，一些相同的部分無(wú)法復(fù)用，接口多了文檔會(huì)變的很長(zhǎng)，還經(jīng)常需要調(diào)整格式。2) 發(fā)布不方便。文檔更新時(shí)，需要發(fā)給需要的小伙伴。即使用git來(lái)進(jìn)行管理，雖然拉取比較方便，但由于文件格式的問題，也不方便比較兩次提交的差異。
由于有這些問題，決定尋找一種更優(yōu)雅有效的方式來(lái)編寫文檔。經(jīng)過(guò)比較，發(fā)現(xiàn)了apidoc,可以比較好的解決上面提到的問題。apidoc采用了一種類似寫代碼注釋的方式來(lái)寫文檔，支持編寫多種語(yǔ)言的文檔。最后生成的文檔以網(wǎng)頁(yè)的形式發(fā)布，方便快捷，便于閱讀。下面就來(lái)簡(jiǎn)單介紹一下怎么使用apidoc來(lái)寫文檔。
? ? ?1.安裝node
由于apidoc依賴node.js的包管理工具npm進(jìn)行安裝，所以安裝apidoc之前要先安裝node.js（npm會(huì)在安裝node時(shí)順帶進(jìn)行安裝）。具體的安裝教程可以參考這里。
參考：
http://www.itdecent.cn/p/9a6070565804
? ? 2.安裝apidoc
? ? 安裝完了npm之后，就可以安裝apidoc了。在命令行輸入
Shell代碼
npm?install?apidoc?-g??
? ? ?就可以進(jìn)行安裝了。安裝完成輸入
Shell代碼
apidoc?-h??
? ? 出現(xiàn)相關(guān)的提示幫助信息，說(shuō)明安裝成功了。
? ? 3 apidoc 常用注解介紹
? ? apidoc是運(yùn)用各個(gè)不同的注解來(lái)完成文檔的寫作的。學(xué)習(xí)apidoc，主要就是學(xué)習(xí)注解的用法。apidoc和命名行的命令很像，由一個(gè)注解關(guān)鍵字加一些選項(xiàng)構(gòu)成。下面介紹一下apidoc主要的注解。
Apidoc代碼
@api?{method}?path?[title]??
? ? 這是apidoc必需的注解，用來(lái)說(shuō)明api的方法，訪問路徑和作用。
Apidoc代碼
@apiParam?[(group)]?[{type}]?[field=defaultValue]?[description]??
? ? ? 這個(gè)注解用來(lái)說(shuō)明api請(qǐng)求參數(shù)的類型，大小和作用。
Apidoc代碼
@apiSuccess?[(group)]?[{type}]?field?[description]??
? ? 這個(gè)注解說(shuō)明api返回參數(shù)的類型，大小和作用。
關(guān)于注解的詳細(xì)用法可以訪問官網(wǎng)，上面有詳細(xì)的用法和示例。
? ? ?4.編寫apidoc文檔
? ? 了解了關(guān)于注解的用法之后，就可以用注解來(lái)編寫文檔了。例如我們可以編寫一個(gè)GetUser.java文件。里面的內(nèi)容如下所示：
Java代碼
/**
?*?@api?{get}?/user/:id?Request?User?information
?*?@apiGroup?User
?*
?*?@apiParam?{Number}?id?Users?unique?ID.
?*
?*?@apiSuccess?{String}?firstname?Firstname?of?the?User.
?*?@apiSuccess?{String}?lastname??Lastname?of?the?User.
?*/
? ? 5 生成apidoc文檔
? ? 編寫完成后，運(yùn)行
Shell代碼
apidoc?-i?apidocIn?-o?apidocOut??
? ? apidocIn表示GetUser.java文件的存放目錄，apidocOut表示希望apidoc文檔生成的目錄。運(yùn)行成功后，在輸 ? 出目錄可以看見一堆生成的文件，其中index.html是我們需要的文檔。在瀏覽器打開就可以看見效果了。效果如下圖所示：
注意：apidocIn是指要生成的java文件存放目錄;apidocOut 是指生成文檔的存放目錄。而不是命令??！
? ? ?后面可以配置一下nginx，指定訪問的路徑映射到index.html，就可以讓需要文檔的小伙伴們?cè)L問了
其他相關(guān)apidoc的資料如下：
http://www.itdecent.cn/p/bb5a4f5e588a
get hub地址：
https://github.com/apidoc/apidoc/tree/master/template
參考：https://blog.csdn.net/zhaoruifeng158/article/details/65445960
