本文作者：胡亦萍
業界有非常多優秀的API文檔管理方案，大多都是基於IDE插件或maven插件的方式做集成。本文主要介紹雲音樂自研的基於代碼關係、中心化、自動化的API文檔管理方案。
背景
隨着微服務的發展，在前後端基於API協作的研發模式下，業界涌現了一批優秀的API文檔管理工具，如網易自研的NEI、swagger、yapi、smart-docs等等，這些工具通過圍繞API文檔構建了一系列的能力，極大提升研發效率。
但隨着研發流程的迭代更新，也對API文檔管理提出了更高的要求。雲音樂使用的NEI處於維護階段，相關功能已經無法滿足最新的研發要求，主要體現在：
- 依賴手動更新，比較依賴研發人員，文檔信息變更時容易存在通知遺漏，影響下游測試或對接方獲取最新信息。
- 與研發流程結合度低，NEI是基於項目維護API文檔信息，缺少研發流程信息，與研發流程的其他系統存在割裂。
- API文檔維護與代碼分離嚴重，很多代碼不維護API文檔註釋，信息只維護在NEI，隨着時間的流逝信息的不一致也給維護帶來了問題。
所以我們希望通過構建一個全新的API文檔管理平台，解決當前存在的問題，推進API標準化，同時增強API文檔的生命週期管理，與研發流程更緊密結合，進一步促進研發提效。
思路&方案
思路
API文檔管理平台首先需要確保API文檔準確性，在此基礎上降低研發人員的維護成本，所以我們需要解決以下幾個關鍵問題：
- 如何解決當前存在的文檔與代碼分離帶來的維護問題？
業界的API文檔管理工具基本上都給出了答案，使用javadoc註釋。javadoc作為一個通用的類、方法、成員等註釋提取標準，使用javadoc作為不需要額外的代碼侵入，有天然的優勢，而且市面上的AST工具也都支持javadoc提取；通過javadoc可以非常方便地實現代碼即文檔，降低維護成本。 - 如何及時完成API文檔創建和更新，且同時保證等待耗時較小呢？
雲音樂的代碼都是使用gitlab進行管理，所以我們可以利用gitlab的webhook進行commit信息的推送，基於推送的變更信息做增量解析，避免全量代碼的冗餘處理；同時採用源碼解析方式，減少編譯帶來的時間損耗；但這裏也存在一個問題，就是依賴研發人員及時push代碼。 - 增量的commit其實存在信息缺失的情況，如何保證完整的變更信息被有效識別？
API文檔中的關係包含API與數據模型的關係、數據模型與數據模型的關係。如果我們能夠有效地管理他們的關係，那在增量解析的時候就可以通過這些關係獲取完整的信息，從而進行有效的API文檔更新。使用傳統的數據庫無法高效地維護關係，但圖數據庫能很好地解決這個問題。當某一節點變更時，通過查詢節點間的路徑關係可以快速獲取完整的受影響範圍，從而進行有效的信息更新。
基於上述思考，我們確定了以代碼為依據，基於AST解析的API文檔管理方案。
整體方案
關鍵流程
- 新接入的應用（由研發協作平台通知）做全量的代碼掃描，後續基於gitlab的推送進行增量代碼掃描；全量掃描後生成基線的代碼關係。
- 基於增量代碼分析獲取基礎的變更信息，再基於代碼關係獲取完整的變更影響範圍；每次變更分析後更新代碼關係。。
- 基於完整的變更範圍解析出完整的接口變更信息，更新API文檔。
- 對更新的API文檔進行變更分析，生成變化的差異表；下游可以通過差異表很容易獲取變更的內容。
- 基於代碼所屬應用與需求的關係獲取API的干係人並進行通知。
關係管理
關係管理在是本方案中一個非常重要的支撐，如果關係無法有效管理，就無法實現高效準確的API文檔更新。最終的關係如下圖所示
圖數據庫中管理的關係包含：
- API節點與數據模型節點的關係：請求、響應等。
- 數據模型節點與數據模型節點關係：字段、關聯、繼承等。
其中所有的節點都包含分支屬性，分支屬性在節點中的維護的關係如下：
- 基線關係：master分支節點之間，如DtoA某個字段為DtoB，則關係為DtoA(master)-[field]->DtoB(master)
-
當進行分支開發時：
- 當在dev分支中DtoB節點變更，則此時的關係為DtoA(master)-[field]->DtoB(master)，DtoA(dev)-[field]->DtoB(dev)
- 如DtoA節點變更，則此時的關係為DtoA(master)-[field]->DtoB(master)，DtoA(dev)-[field]->DtoB(master)。
- 如果沒有master分支，只有開發分支，則此時不存在基線關係，所有的分支都按相同分支名維護
功能展示
API文檔詳情
API文檔變更內容
API文檔變更通知
實踐的過程遇到的一些問題
- 因為採用源碼解析，如果API中引用了二方包，會導致API文檔信息缺失
基本二方包的維護也是基於git倉庫，所以我們約定採用相同分支名進行全局匹配的策略（存在極少的相同路徑的情況使用特殊處理）。 -
雖然我們在定API標準的時候希望不要有非標的結構，但在實際的API文檔的維護中，不可避免會有定義Map結構的場景。
針對這種情況，我們通過引入特殊的解析邏輯，如下所示@Data public class AppDTO { /** * 應用id */ private Integer id; /** * 測試map， * * @OxLink key1 描述1 {@link CanvasDTO} * @OxLink key2 描述2 {@link AppDTO} * @OxLink key3 描述3 {@link ComponentDTO} */ private Map<String, Object> addedMap; }
總結
這種代碼即文檔的中心化API文檔管理實踐帶來了許多好處。首先，開發人員只需要在代碼中進行Javadoc的修改，就能自動更新API文檔，大大簡化了文檔維護的工作。其次，這種方案使得大部分場景下的API文檔更新可以在30秒內完成，提高了開發效率。最重要的是，開發人員將API信息維護在代碼中，保證了文檔與實際代碼的一致性。
最後
更多崗位，可進入網易招聘官網查看 https://hr.163.com/
