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

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

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

(資料圖)

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

Smart-Doc

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

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

簡單來說，在簡單配置之后，只要代碼寫的規(guī)范、注釋寫的夠全，就能自動生成文檔，無需對項目邏輯做修改、也不用添加額外注解。

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

Torna

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

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

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

使用方法和配置方法在這(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ù)端。

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

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

效果展示

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

比如有一個接口定義如下：

/** * 產(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  }

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

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

踩過的坑

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

appKey

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

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

appToken

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

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

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

總結(jié)

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

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

總之就是非常不錯，嗯。

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