踐：ShowDoc 私有化部署與自動(dòng)化同步)
1. 先理解 ShowDoc 在 Spring Boot 開發(fā)里到底是什么角色做后端最煩的事情里維護(hù)接口文檔絕對(duì)能排進(jìn)前五。我之前在某團(tuán)隊(duì)接手一個(gè)訂單服務(wù)代碼里接口全有但文檔還停留在上一任同事離職前的 Word 版本前端聯(lián)調(diào)時(shí)對(duì)著舊文檔問(wèn)這個(gè)參數(shù)明明沒(méi)傳啊我一看代碼字段早改名了。就是從那時(shí)候開始我把 Spring Boot API 接口文檔的維護(hù)方式換成了 ShowDoc。這篇東西不是官方教程是我從部署到落地再到團(tuán)隊(duì)一起用起來(lái)的全過(guò)程記錄適合正在糾結(jié)要不要上文檔工具的后端開發(fā)也適合剛把 ShowDoc 裝起來(lái)但不知道怎么接入 Spring Boot 的讀者。1.1 ShowDoc 到底是個(gè)什么工具ShowDoc 從產(chǎn)品形態(tài)上說(shuō)是一個(gè)私有化、可部署的在線文檔系統(tǒng)。它最大的特點(diǎn)不是生成接口文檔而是什么文檔都能往里放。你可以新建一個(gè)接口項(xiàng)目用 Markdown 或富文本維護(hù)每個(gè)接口的 URL、header、請(qǐng)求體、返回示例、錯(cuò)誤碼也可以另開一個(gè)目錄把數(shù)據(jù)庫(kù)字段字典、環(huán)境配置說(shuō)明、部署手冊(cè)全部整理進(jìn)去。對(duì) Spring Boot 項(xiàng)目來(lái)說(shuō)一個(gè)好的接口文檔工具需要滿足三個(gè)條件第一能承載自動(dòng)生成的內(nèi)容第二能支持團(tuán)隊(duì)在線編輯和評(píng)論第三能控制訪問(wèn)權(quán)限。ShowDoc 恰好三點(diǎn)都占。它不像 Swagger UI 那樣只能展示 Swagger 注解生成的結(jié)果也不像某些以調(diào)試為核心的工具那樣只注重能不能調(diào)通它更像一個(gè)圍繞接口資料的內(nèi)部 Wiki接口信息只是其中一類頁(yè)面。1.2 和 Word、Swagger UI 的真實(shí)對(duì)比我在實(shí)際項(xiàng)目里用過(guò) Word、Swagger UI、ShowDoc 三種方式體驗(yàn)差別很大。Word 文檔的問(wèn)題是完全沒(méi)有強(qiáng)約束。誰(shuí)改了代碼不更新 Word沒(méi)人知道多人同時(shí)編輯時(shí)版本互相覆蓋文檔里寫詳見 XX 文檔最后根本找不到。Swagger UI 的問(wèn)題是能看不能用。它確實(shí)能根據(jù)注解實(shí)時(shí)生成接口列表也能在線調(diào)試但字段說(shuō)明、業(yè)務(wù)含義、錯(cuò)誤碼意思、數(shù)據(jù)字典這些靠注解很難寫清楚而且一旦項(xiàng)目多了Swagger UI 的導(dǎo)航會(huì)變得非常難用還經(jīng)常遇到跨域問(wèn)題。ShowDoc 的價(jià)值在于把這幾種工具的長(zhǎng)處合到一起接口列表從 OpenAPI 數(shù)據(jù)導(dǎo)入字段說(shuō)明、錯(cuò)誤碼、更新記錄靠編輯頁(yè)面補(bǔ)充訪問(wèn)權(quán)限按項(xiàng)目劃分歷史版本還能找回。我用下來(lái)最直觀的感受是前端拿到的不再是一堆 JSON schema而是一份他們自己能看懂的接口使用說(shuō)明。1.3 哪些項(xiàng)目適合選 ShowDoc不是所有團(tuán)隊(duì)都適合。如果是單機(jī)小 Demo直接看 Swagger UI 就夠如果團(tuán)隊(duì)規(guī)模很大已經(jīng)在用一體化 API 管理平臺(tái)也沒(méi)必要再引入 ShowDoc。ShowDoc 最合適的場(chǎng)景是接口數(shù)量中等幾十到幾百個(gè)、前后端協(xié)作流程還沒(méi)完全規(guī)范化、需要把接口文檔放在公司內(nèi)網(wǎng)、還需要有人能編輯權(quán)限的團(tuán)隊(duì)。我現(xiàn)在的團(tuán)隊(duì)就是用 Spring Boot 做微服務(wù)每個(gè)服務(wù)一個(gè)工程ShowDoc 按服務(wù)建項(xiàng)目實(shí)踐了半年效果比之前好太多。2. 部署 ShowDoc 服務(wù)我推薦私有化 Docker 方案ShowDoc 官方提供在線版但介于接口文檔通常帶有業(yè)務(wù)信息我不太建議把公司內(nèi)部接口丟給第三方。私有化部署是最穩(wěn)妥的選擇而 Docker 方案最省心。2.1 一條命令跑起來(lái)如果你服務(wù)器上已經(jīng)裝好 Docker啟動(dòng) ShowDoc 其實(shí)就是一句命令docker run -d \ --name showdoc \ --restartalways \ -p 4999:80 \ -v /data/showdoc_data:/var/www/html/ \ showdoc/showdoc這條命令做了三件事把容器命名為 showdoc方便后續(xù)查看日志和啟停用--restartalways保證服務(wù)器重啟后容器自動(dòng)拉起把宿主機(jī)的/data/showdoc_data目錄掛載到容器 Web 根目錄這樣文檔數(shù)據(jù)不會(huì)隨容器刪除而丟失。啟動(dòng)完成后訪問(wèn)http://服務(wù)器IP:4999走完初始化引導(dǎo)用默認(rèn)管理員賬號(hào)登錄并立即改掉密碼。這里特別提醒默認(rèn)端口 80 被很多人掛在公網(wǎng)上掃到過(guò)建議改成不常用端口再配合防火墻只放行內(nèi)網(wǎng) IP 訪問(wèn)。2.2 數(shù)據(jù)備份恢復(fù)的完整做法ShowDoc 的數(shù)據(jù)存在 MySQL 和文件目錄里容器化部署后這些底層細(xì)節(jié)被隱藏了我們只要保證掛載目錄安全就行。我的備份策略很簡(jiǎn)單每天凌晨壓縮整個(gè)掛載目錄保留最近 7 天。tar -czf /backup/showdoc_$(date %F).tar.gz -C /data showdoc_data find /backup -name showdoc_* -mtime 7 -exec rm -f {} \;恢復(fù)操作也直接新服務(wù)器上把備份文件解壓到同樣的/data目錄再跑一遍 docker run 命令數(shù)據(jù)就回來(lái)了。我踩過(guò)一次坑是早期沒(méi)意識(shí)到掛載目錄的重要性升級(jí)容器時(shí)直接刪了容器數(shù)據(jù)全丟。后來(lái)所有 docker run 都帶上-v掛載這個(gè)教訓(xùn)比任何配置都重要。2.3 項(xiàng)目和權(quán)限規(guī)劃要提前做ShowDoc 安裝好后第一件事不是寫接口而是規(guī)劃項(xiàng)目結(jié)構(gòu)。我建議按服務(wù)域建項(xiàng)目比如用戶服務(wù)、訂單服務(wù)、商品服務(wù)而不是把所有接口混到一個(gè)項(xiàng)目里。一個(gè)項(xiàng)目對(duì)應(yīng)一個(gè) ShowDoc 項(xiàng)目權(quán)限好控制文檔也好維護(hù)。在 ShowDoc 后臺(tái)項(xiàng)目可以設(shè)置為私有項(xiàng)目然后手動(dòng)添加成員。角色我習(xí)慣只開兩種后端主程是編輯者其他人是只讀成員。前端同學(xué)一般不需要編輯權(quán)限他們需要的只是穩(wěn)定的只讀地址。如果遇到要臨時(shí)修改文檔的情況再提升權(quán)限避免誤操作污染文檔。這一步看似簡(jiǎn)單但對(duì)后面的自動(dòng)化同步很關(guān)鍵因?yàn)闄?quán)限規(guī)劃直接決定 API Key 的使用范圍。3. Spring Boot 接入 ShowDoc核心是把 Swagger JSON 變成同步任務(wù)ShowDoc 有一個(gè)很實(shí)用的能力對(duì)外開放接口允許你把外部系統(tǒng)生成的文檔內(nèi)容直接寫入指定項(xiàng)目。這就給 Spring Boot 項(xiàng)目提供了一個(gè)自動(dòng)化方案用 SpringDoc 生成 OpenAPI JSON再把 JSON 轉(zhuǎn)成 ShowDoc 需要的頁(yè)面結(jié)構(gòu)最后通過(guò) ShowDoc 開放接口推送上去。3.1 為什么中間格式選 OpenAPI 而不是直接手寫市面上很多人誤以為用 ShowDoc 就等于放棄 Swagger。實(shí)際上兩者是配合關(guān)系。Spring Boot 項(xiàng)目里通過(guò)注解維護(hù)接口信息SpringDoc 會(huì)自動(dòng)生成/v3/api-docs的 OpenAPI JSON。這個(gè) JSON 是標(biāo)準(zhǔn)格式包含接口路徑、方法、參數(shù)、響應(yīng)體和說(shuō)明。ShowDoc 支持導(dǎo)入 OpenAPI 格式數(shù)據(jù)也支持用開放接口創(chuàng)建頁(yè)面。我之所以選擇 OpenAPI 作為中間層是因?yàn)樗鼉蛇叢怀蕴濋_發(fā)時(shí)用注解IDE 能檢查文檔更新時(shí)由腳本把 JSON 轉(zhuǎn)換推送不用人去一個(gè)個(gè)復(fù)制參數(shù)。如果哪一天團(tuán)隊(duì)決定換文檔工具OpenAPI JSON 還能繼續(xù)導(dǎo)入別的平臺(tái)數(shù)據(jù)不會(huì)被綁死。3.2 Spring Boot 側(cè)配置 SpringDoc在 Spring Boot 工程里加入 springdoc-openapi 依賴后它自動(dòng)掃描 Controller 上的注解。下面是基礎(chǔ)配置springdoc: api-docs: enabled: true path: /v3/api-docs swagger-ui: path: /swagger-ui.html啟動(dòng)項(xiàng)目后訪問(wèn)http://localhost:8080/v3/api-docs能看到一個(gè)很大的 JSON這就是 OpenAPI 數(shù)據(jù)。為了讓這個(gè) JSON 內(nèi)容夠完整Controller 類和方法上的注解要寫全稍后我會(huì)在第四節(jié)專門講字段規(guī)范。這里先記住一個(gè)原則注解里寫清楚的內(nèi)容會(huì)原樣進(jìn)入 ShowDoc注解里沒(méi)有的內(nèi)容后面就得靠手工補(bǔ)工作量大得多。3.3 同步服務(wù)的核心代碼ShowDoc 的開放接口邏輯是準(zhǔn)備好 API Key、API Token、項(xiàng)目 ID然后把文檔內(nèi)容 POST 上去。不同部署地址的開放接口路徑可能不一樣去后臺(tái)的開放 API頁(yè)面能看到當(dāng)前地址對(duì)應(yīng)的示例。我封裝的同步服務(wù)簡(jiǎn)化后是這樣Service public class ShowDocSyncService { private final RestTemplate restTemplate new RestTemplate(); Value(${showdoc.api-url}) private String apiUrl; Value(${showdoc.api-key}) private String apiKey; Value(${showdoc.api-token}) private String apiToken; Value(${showdoc.item-id}) private String itemId; public void syncFromSwagger(String swaggerJson) { // 這里把 OpenAPI JSON 轉(zhuǎn)換成 ShowDoc 的目錄和頁(yè)面結(jié)構(gòu) // 推薦的做法是遍歷 paths 節(jié)點(diǎn) // 每個(gè) tag 作為一個(gè)目錄每個(gè) pathmethod 作為一個(gè)頁(yè)面 ListMapString, Object catalogs Converter.toShowDocPages(swaggerJson); MultiValueMapString, String params new LinkedMultiValueMap(); params.add(api_key, apiKey); params.add(api_token, apiToken); params.add(item_id, itemId); params.add(data, JacksonUtils.toJson(catalogs)); ResponseEntityString response restTemplate.postForEntity(apiUrl, params, String.class); // 判斷 response body 中的狀態(tài)失敗則拋出異常 } }這個(gè)類的重點(diǎn)在Converter.toShowDocPages它負(fù)責(zé)把 Swagger JSON 里的paths和tags映射成 ShowDoc 頁(yè)面層級(jí)。比如一個(gè)用戶管理 tag 下有三個(gè)接口最終在 ShowDoc 里就是一個(gè)用戶管理目錄下面掛著三個(gè)接口頁(yè)面。轉(zhuǎn)換邏輯不難但要注意幾個(gè)問(wèn)題。第一OpenAPI 里同一個(gè) path 可能對(duì)應(yīng)多個(gè) HTTP 方法比如/user/{id}有 GET 和 PUT頁(yè)面標(biāo)題要帶上[GET]前綴否則同名頁(yè)面會(huì)互相覆蓋。第二ShowDoc 的頁(yè)面內(nèi)容是 Markdown轉(zhuǎn)換時(shí)要把請(qǐng)求體、響應(yīng)體、參數(shù)表轉(zhuǎn)成 Markdown 表格才能保證前端閱讀體驗(yàn)。第三不要把所有接口塞到一個(gè)頁(yè)面按接口頁(yè)面拆分方便單獨(dú)維護(hù)。3.4 觸發(fā)方式手動(dòng)按鈕 CI 自動(dòng)同步同步代碼寫好后觸發(fā)方式我推薦兩個(gè)層面。開發(fā)階段寫一個(gè) Spring Boot 單元測(cè)試或一個(gè)ApplicationRunner啟動(dòng)時(shí)打一個(gè)開關(guān)需要時(shí)手動(dòng)調(diào)用 sync 方法。發(fā)布階段在 CI 構(gòu)建腳本里加一段請(qǐng)求讓測(cè)試通過(guò)后自動(dòng)執(zhí)行同步。# 假設(shè)同步服務(wù)本身也暴露了一個(gè)受保護(hù)的 HTTP 接口 /sync/api-docs curl -X POST http://localhost:8080/sync/api-docs \ -H Content-Type: application/json \ -d {secret:your-sync-token}這里有一個(gè)特別容易踩的坑同步接口不要不加保護(hù)地暴露到公網(wǎng)。用 ShowDoc 開放接口時(shí)API Token 本身是一個(gè)高權(quán)限憑據(jù)任何拿到它的人都能直接修改文檔。所以代碼倉(cāng)庫(kù)里絕對(duì)不能提交真實(shí) token要用環(huán)境變量注入同步接口也要加一層自己的簽名。4. 讓文檔真正好用接口內(nèi)容規(guī)范比工具選型更重要我見過(guò)不少團(tuán)隊(duì)工具從 Word 換到 ShowDoc文檔還是一團(tuán)糟。原因很簡(jiǎn)單工具解決的是放哪不解決寫什么。Spring Boot 接口文檔要讓人愿意看核心是把字段、返回值、錯(cuò)誤碼這三件事說(shuō)清楚。4.1 統(tǒng)一返回結(jié)構(gòu)文檔里只放一個(gè)真實(shí)示例很多 Spring Boot 項(xiàng)目用ResultT包一層這沒(méi)問(wèn)題但接口文檔里最常見的錯(cuò)誤是所有接口的返回示例都寫成{code:0, message:成功, data:{}}data 里面到底長(zhǎng)什么樣完全沒(méi)說(shuō)。前端拿到這種文檔還是得來(lái)問(wèn)你。我的習(xí)慣是在 Controller 的注解里直接用具體響應(yīng)對(duì)象讓生成的 OpenAPI JSON 里能看到 data 的結(jié)構(gòu)。比如Operation(summary 查詢訂單詳情) GetMapping(/order/{id}) public ResultOrderDetailVO getOrder(PathVariable Long id) { return Result.success(orderService.getDetail(id)); }然后在OrderDetailVO的每個(gè)字段上寫Schema(description 訂單狀態(tài)0-待支付1-已支付2-已取消)。這樣 Swagger JSON 里的字段說(shuō)明完整同步到 ShowDoc 后前端就能直接看到 data 結(jié)構(gòu)而不是一個(gè)空的{}。4.2 字段說(shuō)明的五個(gè)必填項(xiàng)寫字段說(shuō)明時(shí)我要求團(tuán)隊(duì)每個(gè)字段至少回答五個(gè)問(wèn)題字段名是什么類型是什么string / integer / boolean / object / array是否必傳取值范圍或枚舉含義一個(gè)真實(shí)可用的示例值。舉個(gè)例子訂單狀態(tài)如果只寫狀態(tài)兩個(gè)字前端大概率搞不清楚如果寫成訂單狀態(tài)可選值1待支付、2已支付、3已取消示例2聯(lián)調(diào)效率會(huì)高很多。這些內(nèi)容都可以直接寫在Schema注解里。需要注意注解里的example屬性會(huì)進(jìn)入 OpenAPI JSONShowDoc 轉(zhuǎn)換后也可以保留所以示例值一定要填別嫌麻煩。4.3 錯(cuò)誤碼單獨(dú)維護(hù)一個(gè)頁(yè)面HTTP 狀態(tài)碼和業(yè)務(wù)錯(cuò)誤碼是兩碼事。很多接口返回 HTTP 200但業(yè)務(wù) code 是 10001 表示訂單不存在。如果文檔里不把業(yè)務(wù)錯(cuò)誤碼列清楚前端同事只能靠猜。我在 ShowDoc 項(xiàng)目里固定建一個(gè)錯(cuò)誤碼說(shuō)明目錄用 Markdown 表格維護(hù)所有業(yè)務(wù) code、含義、建議處理方式。這個(gè)目錄用腳本自動(dòng)同步時(shí)不要覆蓋保留給人工維護(hù)。錯(cuò)誤碼的規(guī)范要用排除法所有接口共用一個(gè) code 字段不要某個(gè)接口返回success、另一個(gè)接口返回status這種不一致是文檔大忌。4.4 目錄結(jié)構(gòu)要有頭腦不要全部堆在頂層ShowDoc 的項(xiàng)目頁(yè)面是按目錄組織的。目錄建議按業(yè)務(wù)模塊而不是Controller 類來(lái)建。比如訂單服務(wù)下面分訂單查詢訂單操作售后流程這樣前端按業(yè)務(wù)場(chǎng)景找接口比按類名一個(gè)一個(gè)翻要快。另外我會(huì)給每個(gè)模塊目錄配一個(gè)使用說(shuō)明頁(yè)面寫清楚這個(gè)模塊的業(yè)務(wù)背景、通用 header、必填 token、分頁(yè)規(guī)則。這類頁(yè)面用自動(dòng)化腳本創(chuàng)建一次就不動(dòng)了后續(xù)手工補(bǔ)充。把自動(dòng)同步生成的頁(yè)面和手工維護(hù)的頁(yè)面分開是防止腳本覆蓋人工內(nèi)容的最后一道防線。5. 團(tuán)隊(duì)協(xié)作中真正提升效率的四個(gè)習(xí)慣ShowDoc 安裝后如果只是一個(gè)人上傳文檔那它只是一個(gè)網(wǎng)盤。要讓它發(fā)揮價(jià)值必須把它嵌進(jìn)團(tuán)隊(duì)的工作流里。5.1 訪問(wèn)權(quán)限要分清API Key 也要分級(jí)別給前端同學(xué)分配只讀賬號(hào)而不是把項(xiàng)目鏈接直接扔到群里讓大家匿名訪問(wèn)這是我對(duì)團(tuán)隊(duì)的最低要求。只讀賬號(hào)的好處是可追溯、可撤銷新人進(jìn)來(lái)給他開賬號(hào)有人離職直接禁用不用換整個(gè)項(xiàng)目鏈接。對(duì)自動(dòng)化同步用的 API Key 也要單獨(dú)建一個(gè)機(jī)器人賬號(hào)不要拿管理員的 Key 去寫腳本。這樣就算腳本里的 Key 泄露權(quán)限只影響指定項(xiàng)目不會(huì)波及整個(gè) ShowDoc 服務(wù)。這個(gè)問(wèn)題容易被忽視我見過(guò)有團(tuán)隊(duì)把管理員 token 直接寫在前端代碼里最后整個(gè)文檔庫(kù)都被人清空了。5.2 Mock 數(shù)據(jù)與并行開發(fā)后端接口還沒(méi)寫完時(shí)前端最痛苦的是沒(méi)有數(shù)據(jù)可以聯(lián)調(diào)。ShowDoc 的頁(yè)面內(nèi)容本身就是 Markdown可以在里面維護(hù)一份完整的返回示例前端照著示例寫死數(shù)據(jù)先開發(fā)頁(yè)面。等后端好了再切換真實(shí)接口大部分邏輯不用改。這個(gè)方法比單獨(dú)搭 Mock 服務(wù)更輕量。我在實(shí)踐中的體會(huì)是Mock 服務(wù)適合接口數(shù)量大、團(tuán)隊(duì)已經(jīng)有一套流程的場(chǎng)景而 ShowDoc 加約定返回示例的方式適合中小團(tuán)隊(duì)讓前后端先對(duì)齊數(shù)據(jù)結(jié)構(gòu)。關(guān)鍵點(diǎn)在于返回示例必須寫的是真實(shí)數(shù)據(jù)結(jié)構(gòu)不能為了示例好看而編一個(gè)和實(shí)際代碼不一致的字段。否則前端按示例寫的數(shù)據(jù)結(jié)構(gòu)到了聯(lián)調(diào)階段全部要返工比沒(méi)有 Mock 更糟。5.3 把文檔更新動(dòng)作放進(jìn)發(fā)布流程最容易老化的文檔就是沒(méi)人主動(dòng)去更新的文檔。我現(xiàn)在要求只要后端接口有變更代碼合并之前必須把同步腳本跑一遍。這樣才能保證線上文檔和代碼是同一版本。你在 CI 里加一個(gè)步驟構(gòu)建成功后調(diào)用同步接口發(fā)布沒(méi)成功文檔就不會(huì)更新這個(gè)聯(lián)動(dòng)幫團(tuán)隊(duì)省了很多心。CI 腳本里要注意同步接口有網(wǎng)絡(luò)延遲建議加超時(shí)和重試。另外ShowDoc 同步過(guò)程是整體更新還是增量更新取決于你轉(zhuǎn)換器的實(shí)現(xiàn)我這邊是用按目錄重建的方式只更新自動(dòng)生成目錄下的頁(yè)面所以即使同步失敗ShowDoc 上還有上一次的舊數(shù)據(jù)不至于頁(yè)面全空。5.4 文檔變化主動(dòng)通知不要等前端來(lái)問(wèn)ShowDoc 本身不一定有很復(fù)雜的消息通知能力但這不影響我們做變更通知。同步腳本執(zhí)行成功后可以在最后調(diào)用一個(gè)通知地址把本次變更的接口清單發(fā)給協(xié)作群。我習(xí)慣在轉(zhuǎn)換器里記錄本次變更的路徑和方法拼成一段簡(jiǎn)短文本。這樣前端不用天天刷新文檔頁(yè)面看有沒(méi)有更新后端在群里說(shuō)一聲文檔已同步order 模塊新增了下單接口大家自然知道。通知邏輯不要放在同步接口內(nèi)部因?yàn)橥浇涌诳赡鼙欢啻斡|發(fā)應(yīng)該放在調(diào)用方CI 的任務(wù)里或者在同步接口返回結(jié)果后單獨(dú)發(fā)一次通知。這個(gè)細(xì)節(jié)能避免前端收到重復(fù)打擾。6. 兩年用下來(lái)我遇到的坑和最終建議每個(gè)工具都有一套看起來(lái)很美的文檔但真正的價(jià)值藏在坑里。最后這部分全是我的真實(shí)經(jīng)歷。6.1 四個(gè)最容易讓人崩潰的問(wèn)題第一個(gè)坑是升級(jí)容器丟數(shù)據(jù)。我早期用 docker run 部署時(shí)沒(méi)掛載目錄后來(lái)官方鏡像升級(jí)我直接把容器刪了重建結(jié)果所有文檔全部清空。解決辦法上面寫過(guò)掛載目錄 定時(shí)備份雙保險(xiǎn)。第二個(gè)坑是 API Key 泄露。某次代碼審查發(fā)現(xiàn)同步腳本里的 token 被硬編碼在配置文件中而且配置文件不小心被提交到了倉(cāng)庫(kù)。雖然事后改了 token但窗口期內(nèi)知道 token 的人都能改文檔很難追責(zé)?，F(xiàn)在所有密鑰一律走環(huán)境變量倉(cāng)庫(kù)里只放占位符。第三個(gè)坑是自動(dòng)同步覆蓋了手工補(bǔ)充。用了轉(zhuǎn)換器后腳本會(huì)把整個(gè)目錄重建手工維護(hù)的備注被沖掉過(guò)一次。后來(lái)我把自動(dòng)生成的頁(yè)面和手工維護(hù)頁(yè)面放在不同目錄腳本只處理帶自動(dòng)生成標(biāo)記的目錄。第四個(gè)坑是文檔看起來(lái)全但沒(méi)講清。打開頁(yè)面接口路徑、參數(shù)類型都有但沒(méi)有示例值、沒(méi)有枚舉含義前端依然要在群里問(wèn)。這屬于內(nèi)容規(guī)范問(wèn)題不是工具問(wèn)題解決方法是把 4.2 節(jié)五個(gè)必填項(xiàng)作為 Code Review 的一部分后端寫完接口自己先打開 ShowDoc 看一眼再提交。6.2 和其他方案比ShowDoc 的定位在哪里我不否定其他 API 文檔工具但每個(gè)工具的側(cè)重點(diǎn)不同。拿我們常用的對(duì)比維度看對(duì)比維度ShowDocSwagger UI 模式一體化調(diào)試管理平臺(tái)部署成本較低Docker 即可隨應(yīng)用部署較高通常要引入中心化服務(wù)自動(dòng)化程度靠 OpenAPI 轉(zhuǎn)換 開放接口本身自動(dòng)生成支持多渠道導(dǎo)入在線調(diào)試較弱不擅長(zhǎng)調(diào)試較好直接試接口很強(qiáng)集環(huán)境、斷言、集合團(tuán)隊(duì)協(xié)作權(quán)限、目錄、成員管理完善無(wú)權(quán)限概念偏平臺(tái)化適合較大團(tuán)隊(duì)私有化方便適合內(nèi)網(wǎng)隨服務(wù)內(nèi)網(wǎng)部署看版本多需商業(yè)授權(quán)如果你們團(tuán)隊(duì)接口數(shù)量多到需要集合管理、調(diào)試、Mock、自動(dòng)化測(cè)試那一體化管理平臺(tái)可能是更好的選擇。但對(duì)大部分中小團(tuán)隊(duì)ShowDoc 的輕量、私有化、配合 OpenAPI 自動(dòng)同步已經(jīng)能解決 80% 的問(wèn)題。工具換得越頻繁團(tuán)隊(duì)對(duì)文檔必須更新的敬畏感越低。6.3 我給正在入門的人三條建議第一條先部署再談規(guī)范。把 ShowDoc 跑起來(lái)手動(dòng)維護(hù)兩個(gè)接口試試手感比空想一個(gè)月都有效。第二條接入自動(dòng)同步前先把 Swagger 注解補(bǔ)完整否則自動(dòng)化推上去的也是垃圾內(nèi)容。第三條接受 ShowDoc 的不完美它不是一個(gè)在線調(diào)試器它是團(tuán)隊(duì)的知識(shí)庫(kù)你需要讓它展示內(nèi)容而不是承擔(dān)所有接口工具的角色。我現(xiàn)在團(tuán)隊(duì)里的日常流程就是Spring Boot 代碼就是規(guī)范SpringDoc 負(fù)責(zé)生成 OpenAPI JSON轉(zhuǎn)換器負(fù)責(zé)把 JSON 變成 ShowDoc 頁(yè)面CI 負(fù)責(zé)在發(fā)布后自動(dòng)同步前端在 ShowDoc 上看文檔、在協(xié)作群里接收變更通知。如果你也準(zhǔn)備把 ShowDoc 引入團(tuán)隊(duì)別追求一步到位。先把服務(wù)跑起來(lái)找兩個(gè)真實(shí)接口維護(hù)出示例然后讓前端把 Word 扔掉再慢慢加自動(dòng)化。工具永遠(yuǎn)不是重點(diǎn)重點(diǎn)是團(tuán)隊(duì)愿不愿意把接口信息當(dāng)成代碼的一部分去維護(hù)。 Spring Boot 接口文檔最佳實(shí)踐：ShowDoc 私有化部署與自動(dòng)化同步
1. 先理解 ShowDoc 在 Spring Boot 開發(fā)里到底是什么角色做后端最煩的事情里維護(hù)接口文檔絕對(duì)能排進(jìn)前五。我之前在某團(tuán)隊(duì)接手一個(gè)訂單服務(wù)代碼里接口全有但文檔還停留在上一任同事離職前的 Word 版本前端聯(lián)調(diào)時(shí)對(duì)著舊文檔問(wèn)這個(gè)參數(shù)明明沒(méi)傳啊我一看代碼字段早改名了。就是從那時(shí)候開始我把 Spring Boot API 接口文檔的維護(hù)方式換成了 ShowDoc。這篇東西不是官方教程是我從部署到落地再到團(tuán)隊(duì)一起用起來(lái)的全過(guò)程記錄適合正在糾結(jié)要不要上文檔工具的后端開發(fā)也適合剛把 ShowDoc 裝起來(lái)但不知道怎么接入 Spring Boot 的讀者。1.1 ShowDoc 到底是個(gè)什么工具ShowDoc 從產(chǎn)品形態(tài)上說(shuō)是一個(gè)私有化、可部署的在線文檔系統(tǒng)。它最大的特點(diǎn)不是生成接口文檔而是什么文檔都能往里放。你可以新建一個(gè)接口項(xiàng)目用 Markdown 或富文本維護(hù)每個(gè)接口的 URL、header、請(qǐng)求體、返回示例、錯(cuò)誤碼也可以另開一個(gè)目錄把數(shù)據(jù)庫(kù)字段字典、環(huán)境配置說(shuō)明、部署手冊(cè)全部整理進(jìn)去。對(duì) Spring Boot 項(xiàng)目來(lái)說(shuō)一個(gè)好的接口文檔工具需要滿足三個(gè)條件第一能承載自動(dòng)生成的內(nèi)容第二能支持團(tuán)隊(duì)在線編輯和評(píng)論第三能控制訪問(wèn)權(quán)限。ShowDoc 恰好三點(diǎn)都占。它不像 Swagger UI 那樣只能展示 Swagger 注解生成的結(jié)果也不像某些以調(diào)試為核心的工具那樣只注重能不能調(diào)通它更像一個(gè)圍繞接口資料的內(nèi)部 Wiki接口信息只是其中一類頁(yè)面。1.2 和 Word、Swagger UI 的真實(shí)對(duì)比我在實(shí)際項(xiàng)目里用過(guò) Word、Swagger UI、ShowDoc 三種方式體驗(yàn)差別很大。Word 文檔的問(wèn)題是完全沒(méi)有強(qiáng)約束。誰(shuí)改了代碼不更新 Word沒(méi)人知道多人同時(shí)編輯時(shí)版本互相覆蓋文檔里寫詳見 XX 文檔最后根本找不到。Swagger UI 的問(wèn)題是能看不能用。它確實(shí)能根據(jù)注解實(shí)時(shí)生成接口列表也能在線調(diào)試但字段說(shuō)明、業(yè)務(wù)含義、錯(cuò)誤碼意思、數(shù)據(jù)字典這些靠注解很難寫清楚而且一旦項(xiàng)目多了Swagger UI 的導(dǎo)航會(huì)變得非常難用還經(jīng)常遇到跨域問(wèn)題。ShowDoc 的價(jià)值在于把這幾種工具的長(zhǎng)處合到一起接口列表從 OpenAPI 數(shù)據(jù)導(dǎo)入字段說(shuō)明、錯(cuò)誤碼、更新記錄靠編輯頁(yè)面補(bǔ)充訪問(wèn)權(quán)限按項(xiàng)目劃分歷史版本還能找回。我用下來(lái)最直觀的感受是前端拿到的不再是一堆 JSON schema而是一份他們自己能看懂的接口使用說(shuō)明。1.3 哪些項(xiàng)目適合選 ShowDoc不是所有團(tuán)隊(duì)都適合。如果是單機(jī)小 Demo直接看 Swagger UI 就夠如果團(tuán)隊(duì)規(guī)模很大已經(jīng)在用一體化 API 管理平臺(tái)也沒(méi)必要再引入 ShowDoc。ShowDoc 最合適的場(chǎng)景是接口數(shù)量中等幾十到幾百個(gè)、前后端協(xié)作流程還沒(méi)完全規(guī)范化、需要把接口文檔放在公司內(nèi)網(wǎng)、還需要有人能編輯權(quán)限的團(tuán)隊(duì)。我現(xiàn)在的團(tuán)隊(duì)就是用 Spring Boot 做微服務(wù)每個(gè)服務(wù)一個(gè)工程ShowDoc 按服務(wù)建項(xiàng)目實(shí)踐了半年效果比之前好太多。2. 部署 ShowDoc 服務(wù)我推薦私有化 Docker 方案ShowDoc 官方提供在線版但介于接口文檔通常帶有業(yè)務(wù)信息我不太建議把公司內(nèi)部接口丟給第三方。私有化部署是最穩(wěn)妥的選擇而 Docker 方案最省心。2.1 一條命令跑起來(lái)如果你服務(wù)器上已經(jīng)裝好 Docker啟動(dòng) ShowDoc 其實(shí)就是一句命令docker run -d \ --name showdoc \ --restartalways \ -p 4999:80 \ -v /data/showdoc_data:/var/www/html/ \ showdoc/showdoc這條命令做了三件事把容器命名為 showdoc方便后續(xù)查看日志和啟停用--restartalways保證服務(wù)器重啟后容器自動(dòng)拉起把宿主機(jī)的/data/showdoc_data目錄掛載到容器 Web 根目錄這樣文檔數(shù)據(jù)不會(huì)隨容器刪除而丟失。啟動(dòng)完成后訪問(wèn)http://服務(wù)器IP:4999走完初始化引導(dǎo)用默認(rèn)管理員賬號(hào)登錄并立即改掉密碼。這里特別提醒默認(rèn)端口 80 被很多人掛在公網(wǎng)上掃到過(guò)建議改成不常用端口再配合防火墻只放行內(nèi)網(wǎng) IP 訪問(wèn)。2.2 數(shù)據(jù)備份恢復(fù)的完整做法ShowDoc 的數(shù)據(jù)存在 MySQL 和文件目錄里容器化部署后這些底層細(xì)節(jié)被隱藏了我們只要保證掛載目錄安全就行。我的備份策略很簡(jiǎn)單每天凌晨壓縮整個(gè)掛載目錄保留最近 7 天。tar -czf /backup/showdoc_$(date %F).tar.gz -C /data showdoc_data find /backup -name showdoc_* -mtime 7 -exec rm -f {} \;恢復(fù)操作也直接新服務(wù)器上把備份文件解壓到同樣的/data目錄再跑一遍 docker run 命令數(shù)據(jù)就回來(lái)了。我踩過(guò)一次坑是早期沒(méi)意識(shí)到掛載目錄的重要性升級(jí)容器時(shí)直接刪了容器數(shù)據(jù)全丟。后來(lái)所有 docker run 都帶上-v掛載這個(gè)教訓(xùn)比任何配置都重要。2.3 項(xiàng)目和權(quán)限規(guī)劃要提前做ShowDoc 安裝好后第一件事不是寫接口而是規(guī)劃項(xiàng)目結(jié)構(gòu)。我建議按服務(wù)域建項(xiàng)目比如用戶服務(wù)、訂單服務(wù)、商品服務(wù)而不是把所有接口混到一個(gè)項(xiàng)目里。一個(gè)項(xiàng)目對(duì)應(yīng)一個(gè) ShowDoc 項(xiàng)目權(quán)限好控制文檔也好維護(hù)。在 ShowDoc 后臺(tái)項(xiàng)目可以設(shè)置為私有項(xiàng)目然后手動(dòng)添加成員。角色我習(xí)慣只開兩種后端主程是編輯者其他人是只讀成員。前端同學(xué)一般不需要編輯權(quán)限他們需要的只是穩(wěn)定的只讀地址。如果遇到要臨時(shí)修改文檔的情況再提升權(quán)限避免誤操作污染文檔。這一步看似簡(jiǎn)單但對(duì)后面的自動(dòng)化同步很關(guān)鍵因?yàn)闄?quán)限規(guī)劃直接決定 API Key 的使用范圍。3. Spring Boot 接入 ShowDoc核心是把 Swagger JSON 變成同步任務(wù)ShowDoc 有一個(gè)很實(shí)用的能力對(duì)外開放接口允許你把外部系統(tǒng)生成的文檔內(nèi)容直接寫入指定項(xiàng)目。這就給 Spring Boot 項(xiàng)目提供了一個(gè)自動(dòng)化方案用 SpringDoc 生成 OpenAPI JSON再把 JSON 轉(zhuǎn)成 ShowDoc 需要的頁(yè)面結(jié)構(gòu)最后通過(guò) ShowDoc 開放接口推送上去。3.1 為什么中間格式選 OpenAPI 而不是直接手寫市面上很多人誤以為用 ShowDoc 就等于放棄 Swagger。實(shí)際上兩者是配合關(guān)系。Spring Boot 項(xiàng)目里通過(guò)注解維護(hù)接口信息SpringDoc 會(huì)自動(dòng)生成/v3/api-docs的 OpenAPI JSON。這個(gè) JSON 是標(biāo)準(zhǔn)格式包含接口路徑、方法、參數(shù)、響應(yīng)體和說(shuō)明。ShowDoc 支持導(dǎo)入 OpenAPI 格式數(shù)據(jù)也支持用開放接口創(chuàng)建頁(yè)面。我之所以選擇 OpenAPI 作為中間層是因?yàn)樗鼉蛇叢怀蕴濋_發(fā)時(shí)用注解IDE 能檢查文檔更新時(shí)由腳本把 JSON 轉(zhuǎn)換推送不用人去一個(gè)個(gè)復(fù)制參數(shù)。如果哪一天團(tuán)隊(duì)決定換文檔工具OpenAPI JSON 還能繼續(xù)導(dǎo)入別的平臺(tái)數(shù)據(jù)不會(huì)被綁死。3.2 Spring Boot 側(cè)配置 SpringDoc在 Spring Boot 工程里加入 springdoc-openapi 依賴后它自動(dòng)掃描 Controller 上的注解。下面是基礎(chǔ)配置springdoc: api-docs: enabled: true path: /v3/api-docs swagger-ui: path: /swagger-ui.html啟動(dòng)項(xiàng)目后訪問(wèn)http://localhost:8080/v3/api-docs能看到一個(gè)很大的 JSON這就是 OpenAPI 數(shù)據(jù)。為了讓這個(gè) JSON 內(nèi)容夠完整Controller 類和方法上的注解要寫全稍后我會(huì)在第四節(jié)專門講字段規(guī)范。這里先記住一個(gè)原則注解里寫清楚的內(nèi)容會(huì)原樣進(jìn)入 ShowDoc注解里沒(méi)有的內(nèi)容后面就得靠手工補(bǔ)工作量大得多。3.3 同步服務(wù)的核心代碼ShowDoc 的開放接口邏輯是準(zhǔn)備好 API Key、API Token、項(xiàng)目 ID然后把文檔內(nèi)容 POST 上去。不同部署地址的開放接口路徑可能不一樣去后臺(tái)的開放 API頁(yè)面能看到當(dāng)前地址對(duì)應(yīng)的示例。我封裝的同步服務(wù)簡(jiǎn)化后是這樣Service public class ShowDocSyncService { private final RestTemplate restTemplate new RestTemplate(); Value(${showdoc.api-url}) private String apiUrl; Value(${showdoc.api-key}) private String apiKey; Value(${showdoc.api-token}) private String apiToken; Value(${showdoc.item-id}) private String itemId; public void syncFromSwagger(String swaggerJson) { // 這里把 OpenAPI JSON 轉(zhuǎn)換成 ShowDoc 的目錄和頁(yè)面結(jié)構(gòu) // 推薦的做法是遍歷 paths 節(jié)點(diǎn) // 每個(gè) tag 作為一個(gè)目錄每個(gè) pathmethod 作為一個(gè)頁(yè)面 ListMapString, Object catalogs Converter.toShowDocPages(swaggerJson); MultiValueMapString, String params new LinkedMultiValueMap(); params.add(api_key, apiKey); params.add(api_token, apiToken); params.add(item_id, itemId); params.add(data, JacksonUtils.toJson(catalogs)); ResponseEntityString response restTemplate.postForEntity(apiUrl, params, String.class); // 判斷 response body 中的狀態(tài)失敗則拋出異常 } }這個(gè)類的重點(diǎn)在Converter.toShowDocPages它負(fù)責(zé)把 Swagger JSON 里的paths和tags映射成 ShowDoc 頁(yè)面層級(jí)。比如一個(gè)用戶管理 tag 下有三個(gè)接口最終在 ShowDoc 里就是一個(gè)用戶管理目錄下面掛著三個(gè)接口頁(yè)面。轉(zhuǎn)換邏輯不難但要注意幾個(gè)問(wèn)題。第一OpenAPI 里同一個(gè) path 可能對(duì)應(yīng)多個(gè) HTTP 方法比如/user/{id}有 GET 和 PUT頁(yè)面標(biāo)題要帶上[GET]前綴否則同名頁(yè)面會(huì)互相覆蓋。第二ShowDoc 的頁(yè)面內(nèi)容是 Markdown轉(zhuǎn)換時(shí)要把請(qǐng)求體、響應(yīng)體、參數(shù)表轉(zhuǎn)成 Markdown 表格才能保證前端閱讀體驗(yàn)。第三不要把所有接口塞到一個(gè)頁(yè)面按接口頁(yè)面拆分方便單獨(dú)維護(hù)。3.4 觸發(fā)方式手動(dòng)按鈕 CI 自動(dòng)同步同步代碼寫好后觸發(fā)方式我推薦兩個(gè)層面。開發(fā)階段寫一個(gè) Spring Boot 單元測(cè)試或一個(gè)ApplicationRunner啟動(dòng)時(shí)打一個(gè)開關(guān)需要時(shí)手動(dòng)調(diào)用 sync 方法。發(fā)布階段在 CI 構(gòu)建腳本里加一段請(qǐng)求讓測(cè)試通過(guò)后自動(dòng)執(zhí)行同步。# 假設(shè)同步服務(wù)本身也暴露了一個(gè)受保護(hù)的 HTTP 接口 /sync/api-docs curl -X POST http://localhost:8080/sync/api-docs \ -H Content-Type: application/json \ -d {secret:your-sync-token}這里有一個(gè)特別容易踩的坑同步接口不要不加保護(hù)地暴露到公網(wǎng)。用 ShowDoc 開放接口時(shí)API Token 本身是一個(gè)高權(quán)限憑據(jù)任何拿到它的人都能直接修改文檔。所以代碼倉(cāng)庫(kù)里絕對(duì)不能提交真實(shí) token要用環(huán)境變量注入同步接口也要加一層自己的簽名。4. 讓文檔真正好用接口內(nèi)容規(guī)范比工具選型更重要我見過(guò)不少團(tuán)隊(duì)工具從 Word 換到 ShowDoc文檔還是一團(tuán)糟。原因很簡(jiǎn)單工具解決的是放哪不解決寫什么。Spring Boot 接口文檔要讓人愿意看核心是把字段、返回值、錯(cuò)誤碼這三件事說(shuō)清楚。4.1 統(tǒng)一返回結(jié)構(gòu)文檔里只放一個(gè)真實(shí)示例很多 Spring Boot 項(xiàng)目用ResultT包一層這沒(méi)問(wèn)題但接口文檔里最常見的錯(cuò)誤是所有接口的返回示例都寫成{code:0, message:成功, data:{}}data 里面到底長(zhǎng)什么樣完全沒(méi)說(shuō)。前端拿到這種文檔還是得來(lái)問(wèn)你。我的習(xí)慣是在 Controller 的注解里直接用具體響應(yīng)對(duì)象讓生成的 OpenAPI JSON 里能看到 data 的結(jié)構(gòu)。比如Operation(summary 查詢訂單詳情) GetMapping(/order/{id}) public ResultOrderDetailVO getOrder(PathVariable Long id) { return Result.success(orderService.getDetail(id)); }然后在OrderDetailVO的每個(gè)字段上寫Schema(description 訂單狀態(tài)0-待支付1-已支付2-已取消)。這樣 Swagger JSON 里的字段說(shuō)明完整同步到 ShowDoc 后前端就能直接看到 data 結(jié)構(gòu)而不是一個(gè)空的{}。4.2 字段說(shuō)明的五個(gè)必填項(xiàng)寫字段說(shuō)明時(shí)我要求團(tuán)隊(duì)每個(gè)字段至少回答五個(gè)問(wèn)題字段名是什么類型是什么string / integer / boolean / object / array是否必傳取值范圍或枚舉含義一個(gè)真實(shí)可用的示例值。舉個(gè)例子訂單狀態(tài)如果只寫狀態(tài)兩個(gè)字前端大概率搞不清楚如果寫成訂單狀態(tài)可選值1待支付、2已支付、3已取消示例2聯(lián)調(diào)效率會(huì)高很多。這些內(nèi)容都可以直接寫在Schema注解里。需要注意注解里的example屬性會(huì)進(jìn)入 OpenAPI JSONShowDoc 轉(zhuǎn)換后也可以保留所以示例值一定要填別嫌麻煩。4.3 錯(cuò)誤碼單獨(dú)維護(hù)一個(gè)頁(yè)面HTTP 狀態(tài)碼和業(yè)務(wù)錯(cuò)誤碼是兩碼事。很多接口返回 HTTP 200但業(yè)務(wù) code 是 10001 表示訂單不存在。如果文檔里不把業(yè)務(wù)錯(cuò)誤碼列清楚前端同事只能靠猜。我在 ShowDoc 項(xiàng)目里固定建一個(gè)錯(cuò)誤碼說(shuō)明目錄用 Markdown 表格維護(hù)所有業(yè)務(wù) code、含義、建議處理方式。這個(gè)目錄用腳本自動(dòng)同步時(shí)不要覆蓋保留給人工維護(hù)。錯(cuò)誤碼的規(guī)范要用排除法所有接口共用一個(gè) code 字段不要某個(gè)接口返回success、另一個(gè)接口返回status這種不一致是文檔大忌。4.4 目錄結(jié)構(gòu)要有頭腦不要全部堆在頂層ShowDoc 的項(xiàng)目頁(yè)面是按目錄組織的。目錄建議按業(yè)務(wù)模塊而不是Controller 類來(lái)建。比如訂單服務(wù)下面分訂單查詢訂單操作售后流程這樣前端按業(yè)務(wù)場(chǎng)景找接口比按類名一個(gè)一個(gè)翻要快。另外我會(huì)給每個(gè)模塊目錄配一個(gè)使用說(shuō)明頁(yè)面寫清楚這個(gè)模塊的業(yè)務(wù)背景、通用 header、必填 token、分頁(yè)規(guī)則。這類頁(yè)面用自動(dòng)化腳本創(chuàng)建一次就不動(dòng)了后續(xù)手工補(bǔ)充。把自動(dòng)同步生成的頁(yè)面和手工維護(hù)的頁(yè)面分開是防止腳本覆蓋人工內(nèi)容的最后一道防線。5. 團(tuán)隊(duì)協(xié)作中真正提升效率的四個(gè)習(xí)慣ShowDoc 安裝后如果只是一個(gè)人上傳文檔那它只是一個(gè)網(wǎng)盤。要讓它發(fā)揮價(jià)值必須把它嵌進(jìn)團(tuán)隊(duì)的工作流里。5.1 訪問(wèn)權(quán)限要分清API Key 也要分級(jí)別給前端同學(xué)分配只讀賬號(hào)而不是把項(xiàng)目鏈接直接扔到群里讓大家匿名訪問(wèn)這是我對(duì)團(tuán)隊(duì)的最低要求。只讀賬號(hào)的好處是可追溯、可撤銷新人進(jìn)來(lái)給他開賬號(hào)有人離職直接禁用不用換整個(gè)項(xiàng)目鏈接。對(duì)自動(dòng)化同步用的 API Key 也要單獨(dú)建一個(gè)機(jī)器人賬號(hào)不要拿管理員的 Key 去寫腳本。這樣就算腳本里的 Key 泄露權(quán)限只影響指定項(xiàng)目不會(huì)波及整個(gè) ShowDoc 服務(wù)。這個(gè)問(wèn)題容易被忽視我見過(guò)有團(tuán)隊(duì)把管理員 token 直接寫在前端代碼里最后整個(gè)文檔庫(kù)都被人清空了。5.2 Mock 數(shù)據(jù)與并行開發(fā)后端接口還沒(méi)寫完時(shí)前端最痛苦的是沒(méi)有數(shù)據(jù)可以聯(lián)調(diào)。ShowDoc 的頁(yè)面內(nèi)容本身就是 Markdown可以在里面維護(hù)一份完整的返回示例前端照著示例寫死數(shù)據(jù)先開發(fā)頁(yè)面。等后端好了再切換真實(shí)接口大部分邏輯不用改。這個(gè)方法比單獨(dú)搭 Mock 服務(wù)更輕量。我在實(shí)踐中的體會(huì)是Mock 服務(wù)適合接口數(shù)量大、團(tuán)隊(duì)已經(jīng)有一套流程的場(chǎng)景而 ShowDoc 加約定返回示例的方式適合中小團(tuán)隊(duì)讓前后端先對(duì)齊數(shù)據(jù)結(jié)構(gòu)。關(guān)鍵點(diǎn)在于返回示例必須寫的是真實(shí)數(shù)據(jù)結(jié)構(gòu)不能為了示例好看而編一個(gè)和實(shí)際代碼不一致的字段。否則前端按示例寫的數(shù)據(jù)結(jié)構(gòu)到了聯(lián)調(diào)階段全部要返工比沒(méi)有 Mock 更糟。5.3 把文檔更新動(dòng)作放進(jìn)發(fā)布流程最容易老化的文檔就是沒(méi)人主動(dòng)去更新的文檔。我現(xiàn)在要求只要后端接口有變更代碼合并之前必須把同步腳本跑一遍。這樣才能保證線上文檔和代碼是同一版本。你在 CI 里加一個(gè)步驟構(gòu)建成功后調(diào)用同步接口發(fā)布沒(méi)成功文檔就不會(huì)更新這個(gè)聯(lián)動(dòng)幫團(tuán)隊(duì)省了很多心。CI 腳本里要注意同步接口有網(wǎng)絡(luò)延遲建議加超時(shí)和重試。另外ShowDoc 同步過(guò)程是整體更新還是增量更新取決于你轉(zhuǎn)換器的實(shí)現(xiàn)我這邊是用按目錄重建的方式只更新自動(dòng)生成目錄下的頁(yè)面所以即使同步失敗ShowDoc 上還有上一次的舊數(shù)據(jù)不至于頁(yè)面全空。5.4 文檔變化主動(dòng)通知不要等前端來(lái)問(wèn)ShowDoc 本身不一定有很復(fù)雜的消息通知能力但這不影響我們做變更通知。同步腳本執(zhí)行成功后可以在最后調(diào)用一個(gè)通知地址把本次變更的接口清單發(fā)給協(xié)作群。我習(xí)慣在轉(zhuǎn)換器里記錄本次變更的路徑和方法拼成一段簡(jiǎn)短文本。這樣前端不用天天刷新文檔頁(yè)面看有沒(méi)有更新后端在群里說(shuō)一聲文檔已同步order 模塊新增了下單接口大家自然知道。通知邏輯不要放在同步接口內(nèi)部因?yàn)橥浇涌诳赡鼙欢啻斡|發(fā)應(yīng)該放在調(diào)用方CI 的任務(wù)里或者在同步接口返回結(jié)果后單獨(dú)發(fā)一次通知。這個(gè)細(xì)節(jié)能避免前端收到重復(fù)打擾。6. 兩年用下來(lái)我遇到的坑和最終建議每個(gè)工具都有一套看起來(lái)很美的文檔但真正的價(jià)值藏在坑里。最后這部分全是我的真實(shí)經(jīng)歷。6.1 四個(gè)最容易讓人崩潰的問(wèn)題第一個(gè)坑是升級(jí)容器丟數(shù)據(jù)。我早期用 docker run 部署時(shí)沒(méi)掛載目錄后來(lái)官方鏡像升級(jí)我直接把容器刪了重建結(jié)果所有文檔全部清空。解決辦法上面寫過(guò)掛載目錄 定時(shí)備份雙保險(xiǎn)。第二個(gè)坑是 API Key 泄露。某次代碼審查發(fā)現(xiàn)同步腳本里的 token 被硬編碼在配置文件中而且配置文件不小心被提交到了倉(cāng)庫(kù)。雖然事后改了 token但窗口期內(nèi)知道 token 的人都能改文檔很難追責(zé)?，F(xiàn)在所有密鑰一律走環(huán)境變量倉(cāng)庫(kù)里只放占位符。第三個(gè)坑是自動(dòng)同步覆蓋了手工補(bǔ)充。用了轉(zhuǎn)換器后腳本會(huì)把整個(gè)目錄重建手工維護(hù)的備注被沖掉過(guò)一次。后來(lái)我把自動(dòng)生成的頁(yè)面和手工維護(hù)頁(yè)面放在不同目錄腳本只處理帶自動(dòng)生成標(biāo)記的目錄。第四個(gè)坑是文檔看起來(lái)全但沒(méi)講清。打開頁(yè)面接口路徑、參數(shù)類型都有但沒(méi)有示例值、沒(méi)有枚舉含義前端依然要在群里問(wèn)。這屬于內(nèi)容規(guī)范問(wèn)題不是工具問(wèn)題解決方法是把 4.2 節(jié)五個(gè)必填項(xiàng)作為 Code Review 的一部分后端寫完接口自己先打開 ShowDoc 看一眼再提交。6.2 和其他方案比ShowDoc 的定位在哪里我不否定其他 API 文檔工具但每個(gè)工具的側(cè)重點(diǎn)不同。拿我們常用的對(duì)比維度看對(duì)比維度ShowDocSwagger UI 模式一體化調(diào)試管理平臺(tái)部署成本較低Docker 即可隨應(yīng)用部署較高通常要引入中心化服務(wù)自動(dòng)化程度靠 OpenAPI 轉(zhuǎn)換 開放接口本身自動(dòng)生成支持多渠道導(dǎo)入在線調(diào)試較弱不擅長(zhǎng)調(diào)試較好直接試接口很強(qiáng)集環(huán)境、斷言、集合團(tuán)隊(duì)協(xié)作權(quán)限、目錄、成員管理完善無(wú)權(quán)限概念偏平臺(tái)化適合較大團(tuán)隊(duì)私有化方便適合內(nèi)網(wǎng)隨服務(wù)內(nèi)網(wǎng)部署看版本多需商業(yè)授權(quán)如果你們團(tuán)隊(duì)接口數(shù)量多到需要集合管理、調(diào)試、Mock、自動(dòng)化測(cè)試那一體化管理平臺(tái)可能是更好的選擇。但對(duì)大部分中小團(tuán)隊(duì)ShowDoc 的輕量、私有化、配合 OpenAPI 自動(dòng)同步已經(jīng)能解決 80% 的問(wèn)題。工具換得越頻繁團(tuán)隊(duì)對(duì)文檔必須更新的敬畏感越低。6.3 我給正在入門的人三條建議第一條先部署再談規(guī)范。把 ShowDoc 跑起來(lái)手動(dòng)維護(hù)兩個(gè)接口試試手感比空想一個(gè)月都有效。第二條接入自動(dòng)同步前先把 Swagger 注解補(bǔ)完整否則自動(dòng)化推上去的也是垃圾內(nèi)容。第三條接受 ShowDoc 的不完美它不是一個(gè)在線調(diào)試器它是團(tuán)隊(duì)的知識(shí)庫(kù)你需要讓它展示內(nèi)容而不是承擔(dān)所有接口工具的角色。我現(xiàn)在團(tuán)隊(duì)里的日常流程就是Spring Boot 代碼就是規(guī)范SpringDoc 負(fù)責(zé)生成 OpenAPI JSON轉(zhuǎn)換器負(fù)責(zé)把 JSON 變成 ShowDoc 頁(yè)面CI 負(fù)責(zé)在發(fā)布后自動(dòng)同步前端在 ShowDoc 上看文檔、在協(xié)作群里接收變更通知。如果你也準(zhǔn)備把 ShowDoc 引入團(tuán)隊(duì)別追求一步到位。先把服務(wù)跑起來(lái)找兩個(gè)真實(shí)接口維護(hù)出示例然后讓前端把 Word 扔掉再慢慢加自動(dòng)化。工具永遠(yuǎn)不是重點(diǎn)重點(diǎn)是團(tuán)隊(duì)愿不愿意把接口信息當(dāng)成代碼的一部分去維護(hù)。