在團(tuán)隊(duì)協(xié)作開(kāi)發(fā)項(xiàng)目的時(shí)候，接口文檔承擔(dān)著向其他開(kāi)發(fā)人員說(shuō)明接口相關(guān)信息的重要任務(wù)，因此，一份清晰而又相近的接口文檔至關(guān)重要。

但是，寫(xiě)接口文檔的痛苦想必各位開(kāi)發(fā)人員都體驗(yàn)過(guò)，明明寫(xiě)接口的時(shí)候那么絲滑，寫(xiě)接口文檔的時(shí)候像要老命一樣各種核對(duì)數(shù)據(jù)格式、文檔格式，最后還有可能漏掉那么一些示例導(dǎo)致調(diào)用不成功，繼續(xù)和其他開(kāi)發(fā)溝通……還有接口文檔的更新問(wèn)題，一旦要更新接口文檔，就意味著要給所有用著接口文檔的同事一一聯(lián)系，想想就令人摸不著頭發(fā)……

以上這些讓人頭禿的痛點(diǎn)驅(qū)使著我尋找一個(gè)可以自動(dòng)生成文檔，并且可以將文檔展示在線上的工具。一來(lái)可以省去大量編寫(xiě)接口文檔的時(shí)間，在不受折磨的情況下生成高可靠性的文檔；二來(lái)在更新接口文檔之后，使用的還是同一個(gè)鏈接，不用再一一通知，對(duì)于我這樣的社恐來(lái)說(shuō)簡(jiǎn)直再好不過(guò)。

(資料圖)

那么閑言少敘，進(jìn)入今天的正題，Smart-Doc + Torna的生成和管理接口文檔解決方案。

Smart-Doc

首先放項(xiàng)目地址(https://gitee.com/smart-doc-team/smart-doc)和文檔(https://smart-doc-group.github.io/#/zh-cn/?id=smart-doc)。

smart-doc是一款同時(shí)支持JAVA REST API和Apache Dubbo RPC接口文檔生成的工具，smart-doc在業(yè)內(nèi)率先提出基于JAVA泛型定義推導(dǎo)的理念， 完全基于接口源碼來(lái)分析生成接口文檔，不采用任何注解侵入到業(yè)務(wù)代碼中。你只需要按照java-doc標(biāo)準(zhǔn)編寫(xiě)注釋， smart-doc就能幫你生成一個(gè)簡(jiǎn)易明了的Markdown、HTML5、Postman Collection2.0+、OpenAPI 3.0+的文檔。

簡(jiǎn)單來(lái)說(shuō)，在簡(jiǎn)單配置之后，只要代碼寫(xiě)的規(guī)范、注釋寫(xiě)的夠全，就能自動(dòng)生成文檔，無(wú)需對(duì)項(xiàng)目邏輯做修改、也不用添加額外注解。

配置方法在這(https://smart-doc-group.github.io/#/zh-cn/start/quickstart)。

Torna

還是先放項(xiàng)目地址(https://gitee.com/durcframework/torna)和文檔(https://torna.cn/dev/)。

接口文檔解決方案，目標(biāo)是讓接口文檔管理變得更加方便、快捷。Torna采用團(tuán)隊(duì)協(xié)作的方式管理和維護(hù)接口文檔，將不同形式的文檔納入進(jìn)來(lái)統(tǒng)一維護(hù)。

Torna提供了強(qiáng)大的API管理功能，并且有開(kāi)放的API，通過(guò)這些API可自動(dòng)將文檔推送到Torna企業(yè)級(jí)接口文檔管理平臺(tái)。

使用方法和配置方法在這(https://gitee.com/durcframework/torna#%E4%BD%BF%E7%94%A8%E6%AD%A5%E9%AA%A4)。

Smart-Doc和Torna配合使用前置條件

配合使用的基礎(chǔ)是：

1、Smart-Doc已經(jīng)配置好了，至少成功生成本地文檔。

2、Torna配置好了，成功登錄服務(wù)端。

滿足以上兩點(diǎn)，就可以著手將兩個(gè)模塊接一起了，Torna在官方文檔中也給出了詳細(xì)的方法步驟，點(diǎn)這(https://torna.cn/dev/smart-doc.html#整合smart-doc)。

通過(guò)這套組合可以實(shí)現(xiàn)：只需要寫(xiě)完Java注釋就能把接口信息推送到Torna平臺(tái)，從而實(shí)現(xiàn)接口預(yù)覽、接口調(diào)試。

效果展示

最終的效果就和Torna文檔里展示的一樣，為了方便起見(jiàn)，我直接用文檔的示例做說(shuō)明。

比如有一個(gè)接口定義如下：

/** * 產(chǎn)品模塊 * * @author thc */@RestController@RequestMapping("shop/product")public class ProductController {   /**   * 查詢產(chǎn)品   *   * @param productNo 產(chǎn)品id|123   * @return   */   @GetMapping   public Result get(@RequestParam Integer productNo) {     ProductVO productVO = new ProductVO();     productVO.setProductNo(String.valueOf(productNo));     return Result.ok(productVO);   }}

其中ProductVO的結(jié)構(gòu)是：

public class ProductVO {   /**   * 產(chǎn)品id   *   * @mock aa   */   private String productNo;   /**   * 備注   *   * @mock xxx   */   private String remark;   /**   * 產(chǎn)品詳情   *   * @mock   */   private ProductDetailVO productDetailVO;     ... 省略getter setter  }

那么生成的接口文檔效果如下：

對(duì)照著看一下，可以發(fā)現(xiàn)Smart-Doc + Torna的方案生成的接口文檔，請(qǐng)求參數(shù)和響應(yīng)參數(shù)的描述和示例都非常詳盡，在方便接口對(duì)接的同時(shí)，也大大減輕了開(kāi)發(fā)人員的負(fù)擔(dān)。

踩過(guò)的坑

文檔上的東西還是很細(xì)的，但是在配置和使用過(guò)程中仍然會(huì)踩坑，這里說(shuō)一下踩過(guò)的每一個(gè)坑。

appKey

在Smart-Doc的文檔中提到Torna從1.11.0版本開(kāi)始，使用smart-doc推送文檔數(shù)據(jù)已經(jīng)不再需要配置appKey和secret， 僅需要配置appToken即可，因此建議升級(jí)Torna版本。。我用的版本組合是Smart-Doc:2.5.3+Torna:1.16.3，按文檔的說(shuō)法是不需要配置appKey的，但是在實(shí)際使用中發(fā)現(xiàn)文檔生成后往Torna上推送的時(shí)候怎么都不成功。

后來(lái)在調(diào)試的時(shí)候發(fā)現(xiàn)，推送還是驗(yàn)證了appKey，不過(guò)只要不是null就能通過(guò)驗(yàn)證，所以在每個(gè)模塊的smart-doc.json中都配置了"appKey":"xxx"，然后就推送成功了。

appToken

這個(gè)倒不是跟文檔描述不一致，只是理解出現(xiàn)了偏差。

當(dāng)子模塊有多個(gè)的時(shí)候，需要在torna中新建對(duì)應(yīng)的模塊，每個(gè)模塊有一個(gè)單獨(dú)的appToken，然后給不同的子模塊配置不同的appToken。

我剛開(kāi)始不知道需要給每個(gè)子模塊單獨(dú)配appToken，導(dǎo)致我的文檔推送的時(shí)候，后一個(gè)子模塊就把前一個(gè)子模塊的文檔覆蓋了，只有最后一個(gè)子模塊的文檔能看到。

總結(jié)

Smart-Doc + Torna的生成和管理接口文檔解決方案只需寫(xiě)好注釋、規(guī)范代碼，就能通過(guò)對(duì)注釋和實(shí)體類的解析來(lái)生成示例詳盡的接口文檔，適用范圍很大；由于其對(duì)代碼零侵入的特性，不用改動(dòng)業(yè)務(wù)代碼就能使用，對(duì)舊代碼也很友好。

并且根據(jù)我這倆月的使用體驗(yàn)來(lái)說(shuō)，非常絲滑，還能鞭策我在寫(xiě)代碼的時(shí)候注意代碼規(guī)范、好好寫(xiě)注釋，使我的代碼質(zhì)量有了提升。

總之就是非常不錯(cuò)，嗯。

關(guān)鍵詞： 解決方案 開(kāi)發(fā)人員 團(tuán)隊(duì)協(xié)作