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