1. 先理解 ShowDoc 在 Spring Boot 開發(fā)里到底是什么角色做后端最煩的事情里維護(hù)接口文檔絕對(duì)能排進(jìn)前五。我之前在某團(tuán)隊(duì)接手一個(gè)訂單服務(wù)代碼里接口全有但文檔還停留在上一任同事離職前的 Word 版本前端聯(lián)調(diào)時(shí)對(duì)著舊文檔問這個(gè)參數(shù)明明沒傳啊我一看代碼字段早改名了。就是從那時(shí)候開始我把 Spring Boot API 接口文檔的維護(hù)方式換成了 ShowDoc。這篇東西不是官方教程是我從部署到落地再到團(tuán)隊(duì)一起用起來的全過程記錄適合正在糾結(jié)要不要上文檔工具的后端開發(fā)也適合剛把 ShowDoc 裝起來但不知道怎么接入 Spring Boot 的讀者。1.1 ShowDoc 到底是個(gè)什么工具ShowDoc 從產(chǎn)品形態(tài)上說是一個(gè)私有化、可部署的在線文檔系統(tǒng)。它最大的特點(diǎn)不是生成接口文檔而是什么文檔都能往里放。你可以新建一個(gè)接口項(xiàng)目用 Markdown 或富文本維護(hù)每個(gè)接口的 URL、header、請(qǐng)求體、返回示例、錯(cuò)誤碼也可以另開一個(gè)目錄把數(shù)據(jù)庫字段字典、環(huán)境配置說明、部署手冊(cè)全部整理進(jìn)去。對(duì) Spring Boot 項(xiàng)目來說一個(gè)好的接口文檔工具需要滿足三個(gè)條件第一能承載自動(dòng)生成的內(nèi)容第二能支持團(tuán)隊(duì)在線編輯和評(píng)論第三能控制訪問權(quán)限。ShowDoc 恰好三點(diǎn)都占。它不像 Swagger UI 那樣只能展示 Swagger 注解生成的結(jié)果也不像某些以調(diào)試為核心的工具那樣只注重能不能調(diào)通它更像一個(gè)圍繞接口資料的內(nèi)部 Wiki接口信息只是其中一類頁面。1.2 和 Word、Swagger UI 的真實(shí)對(duì)比我在實(shí)際項(xiàng)目里用過 Word、Swagger UI、ShowDoc 三種方式體驗(yàn)差別很大。Word 文檔的問題是完全沒有強(qiáng)約束。誰改了代碼不更新 Word沒人知道多人同時(shí)編輯時(shí)版本互相覆蓋文檔里寫詳見 XX 文檔最后根本找不到。Swagger UI 的問題是能看不能用。它確實(shí)能根據(jù)注解實(shí)時(shí)生成接口列表也能在線調(diào)試但字段說明、業(yè)務(wù)含義、錯(cuò)誤碼意思、數(shù)據(jù)字典這些靠注解很難寫清楚而且一旦項(xiàng)目多了Swagger UI 的導(dǎo)航會(huì)變得非常難用還經(jīng)常遇到跨域問題。ShowDoc 的價(jià)值在于把這幾種工具的長(zhǎng)處合到一起接口列表從 OpenAPI 數(shù)據(jù)導(dǎo)入字段說明、錯(cuò)誤碼、更新記錄靠編輯頁面補(bǔ)充訪問權(quán)限按項(xiàng)目劃分歷史版本還能找回。我用下來最直觀的感受是前端拿到的不再是一堆 JSON schema而是一份他們自己能看懂的接口使用說明。1.3 哪些項(xiàng)目適合選 ShowDoc不是所有團(tuán)隊(duì)都適合。如果是單機(jī)小 Demo直接看 Swagger UI 就夠如果團(tuán)隊(duì)規(guī)模很大已經(jīng)在用一體化 API 管理平臺(tái)也沒必要再引入 ShowDoc。ShowDoc 最合適的場(chǎng)景是接口數(shù)量中等幾十到幾百個(gè)、前后端協(xié)作流程還沒完全規(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 一條命令跑起來如果你服務(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)完成后訪問http://服務(wù)器IP:4999走完初始化引導(dǎo)用默認(rèn)管理員賬號(hào)登錄并立即改掉密碼。這里特別提醒默認(rèn)端口 80 被很多人掛在公網(wǎng)上掃到過建議改成不常用端口再配合防火墻只放行內(nèi)網(wǎng) IP 訪問。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ù)就回來了。我踩過一次坑是早期沒意識(shí)到掛載目錄的重要性升級(jí)容器時(shí)直接刪了容器數(shù)據(jù)全丟。后來所有 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 需要的頁面結(jié)構(gòu)最后通過 ShowDoc 開放接口推送上去。3.1 為什么中間格式選 OpenAPI 而不是直接手寫市面上很多人誤以為用 ShowDoc 就等于放棄 Swagger。實(shí)際上兩者是配合關(guān)系。Spring Boot 項(xiàng)目里通過注解維護(hù)接口信息SpringDoc 會(huì)自動(dòng)生成/v3/api-docs的 OpenAPI JSON。這個(gè) JSON 是標(biāo)準(zhǔn)格式包含接口路徑、方法、參數(shù)、響應(yīng)體和說明。ShowDoc 支持導(dǎo)入 OpenAPI 格式數(shù)據(jù)也支持用開放接口創(chuàng)建頁面。我之所以選擇 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)目后訪問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注解里沒有的內(nèi)容后面就得靠手工補(bǔ)工作量大得多。3.3 同步服務(wù)的核心代碼ShowDoc 的開放接口邏輯是準(zhǔn)備好 API Key、API Token、項(xiàng)目 ID然后把文檔內(nèi)容 POST 上去。不同部署地址的開放接口路徑可能不一樣去后臺(tái)的開放 API頁面能看到當(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 的目錄和頁面結(jié)構(gòu) // 推薦的做法是遍歷 paths 節(jié)點(diǎn) // 每個(gè) tag 作為一個(gè)目錄每個(gè) pathmethod 作為一個(gè)頁面 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 頁面層級(jí)。比如一個(gè)用戶管理 tag 下有三個(gè)接口最終在 ShowDoc 里就是一個(gè)用戶管理目錄下面掛著三個(gè)接口頁面。轉(zhuǎn)換邏輯不難但要注意幾個(gè)問題。第一OpenAPI 里同一個(gè) path 可能對(duì)應(yīng)多個(gè) HTTP 方法比如/user/{id}有 GET 和 PUT頁面標(biāo)題要帶上[GET]前綴否則同名頁面會(huì)互相覆蓋。第二ShowDoc 的頁面內(nèi)容是 Markdown轉(zhuǎn)換時(shí)要把請(qǐng)求體、響應(yīng)體、參數(shù)表轉(zhuǎn)成 Markdown 表格才能保證前端閱讀體驗(yàn)。第三不要把所有接口塞到一個(gè)頁面按接口頁面拆分方便單獨(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è)試通過后自動(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ù)任何拿到它的人都能直接修改文檔。所以代碼倉庫里絕對(duì)不能提交真實(shí) token要用環(huán)境變量注入同步接口也要加一層自己的簽名。4. 讓文檔真正好用接口內(nèi)容規(guī)范比工具選型更重要我見過不少團(tuán)隊(duì)工具從 Word 換到 ShowDoc文檔還是一團(tuán)糟。原因很簡(jiǎn)單工具解決的是放哪不解決寫什么。Spring Boot 接口文檔要讓人愿意看核心是把字段、返回值、錯(cuò)誤碼這三件事說清楚。4.1 統(tǒng)一返回結(jié)構(gòu)文檔里只放一個(gè)真實(shí)示例很多 Spring Boot 項(xiàng)目用ResultT包一層這沒問題但接口文檔里最常見的錯(cuò)誤是所有接口的返回示例都寫成{code:0, message:成功, data:{}}data 里面到底長(zhǎng)什么樣完全沒說。前端拿到這種文檔還是得來問你。我的習(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 里的字段說明完整同步到 ShowDoc 后前端就能直接看到 data 結(jié)構(gòu)而不是一個(gè)空的{}。4.2 字段說明的五個(gè)必填項(xiàng)寫字段說明時(shí)我要求團(tuán)隊(duì)每個(gè)字段至少回答五個(gè)問題字段名是什么類型是什么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è)頁面HTTP 狀態(tài)碼和業(yè)務(wù)錯(cuò)誤碼是兩碼事。很多接口返回 HTTP 200但業(yè)務(wù) code 是 10001 表示訂單不存在。如果文檔里不把業(yè)務(wù)錯(cuò)誤碼列清楚前端同事只能靠猜。我在 ShowDoc 項(xiàng)目里固定建一個(gè)錯(cuò)誤碼說明目錄用 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è)務(wù)模塊而不是Controller 類來建。比如訂單服務(wù)下面分訂單查詢訂單操作售后流程這樣前端按業(yè)務(wù)場(chǎng)景找接口比按類名一個(gè)一個(gè)翻要快。另外我會(huì)給每個(gè)模塊目錄配一個(gè)使用說明頁面寫清楚這個(gè)模塊的業(yè)務(wù)背景、通用 header、必填 token、分頁規(guī)則。這類頁面用自動(dòng)化腳本創(chuàng)建一次就不動(dòng)了后續(xù)手工補(bǔ)充。把自動(dòng)同步生成的頁面和手工維護(hù)的頁面分開是防止腳本覆蓋人工內(nèi)容的最后一道防線。5. 團(tuán)隊(duì)協(xié)作中真正提升效率的四個(gè)習(xí)慣ShowDoc 安裝后如果只是一個(gè)人上傳文檔那它只是一個(gè)網(wǎng)盤。要讓它發(fā)揮價(jià)值必須把它嵌進(jìn)團(tuán)隊(duì)的工作流里。5.1 訪問權(quán)限要分清API Key 也要分級(jí)別給前端同學(xué)分配只讀賬號(hào)而不是把項(xiàng)目鏈接直接扔到群里讓大家匿名訪問這是我對(duì)團(tuán)隊(duì)的最低要求。只讀賬號(hào)的好處是可追溯、可撤銷新人進(jìn)來給他開賬號(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è)問題容易被忽視我見過有團(tuán)隊(duì)把管理員 token 直接寫在前端代碼里最后整個(gè)文檔庫都被人清空了。5.2 Mock 數(shù)據(jù)與并行開發(fā)后端接口還沒寫完時(shí)前端最痛苦的是沒有數(shù)據(jù)可以聯(lián)調(diào)。ShowDoc 的頁面內(nèi)容本身就是 Markdown可以在里面維護(hù)一份完整的返回示例前端照著示例寫死數(shù)據(jù)先開發(fā)頁面。等后端好了再切換真實(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)階段全部要返工比沒有 Mock 更糟。5.3 把文檔更新動(dòng)作放進(jìn)發(fā)布流程最容易老化的文檔就是沒人主動(dòng)去更新的文檔。我現(xiàn)在要求只要后端接口有變更代碼合并之前必須把同步腳本跑一遍。這樣才能保證線上文檔和代碼是同一版本。你在 CI 里加一個(gè)步驟構(gòu)建成功后調(diào)用同步接口發(fā)布沒成功文檔就不會(huì)更新這個(gè)聯(lián)動(dòng)幫團(tuán)隊(duì)省了很多心。CI 腳本里要注意同步接口有網(wǎng)絡(luò)延遲建議加超時(shí)和重試。另外ShowDoc 同步過程是整體更新還是增量更新取決于你轉(zhuǎn)換器的實(shí)現(xiàn)我這邊是用按目錄重建的方式只更新自動(dòng)生成目錄下的頁面所以即使同步失敗ShowDoc 上還有上一次的舊數(shù)據(jù)不至于頁面全空。5.4 文檔變化主動(dòng)通知不要等前端來問ShowDoc 本身不一定有很復(fù)雜的消息通知能力但這不影響我們做變更通知。同步腳本執(zhí)行成功后可以在最后調(diào)用一個(gè)通知地址把本次變更的接口清單發(fā)給協(xié)作群。我習(xí)慣在轉(zhuǎn)換器里記錄本次變更的路徑和方法拼成一段簡(jiǎn)短文本。這樣前端不用天天刷新文檔頁面看有沒有更新后端在群里說一聲文檔已同步order 模塊新增了下單接口大家自然知道。通知邏輯不要放在同步接口內(nèi)部因?yàn)橥浇涌诳赡鼙欢啻斡|發(fā)應(yīng)該放在調(diào)用方CI 的任務(wù)里或者在同步接口返回結(jié)果后單獨(dú)發(fā)一次通知。這個(gè)細(xì)節(jié)能避免前端收到重復(fù)打擾。6. 兩年用下來我遇到的坑和最終建議每個(gè)工具都有一套看起來很美的文檔但真正的價(jià)值藏在坑里。最后這部分全是我的真實(shí)經(jīng)歷。6.1 四個(gè)最容易讓人崩潰的問題第一個(gè)坑是升級(jí)容器丟數(shù)據(jù)。我早期用 docker run 部署時(shí)沒掛載目錄后來官方鏡像升級(jí)我直接把容器刪了重建結(jié)果所有文檔全部清空。解決辦法上面寫過掛載目錄 定時(shí)備份雙保險(xiǎn)。第二個(gè)坑是 API Key 泄露。某次代碼審查發(fā)現(xiàn)同步腳本里的 token 被硬編碼在配置文件中而且配置文件不小心被提交到了倉庫。雖然事后改了 token但窗口期內(nèi)知道 token 的人都能改文檔很難追責(zé)?，F(xiàn)在所有密鑰一律走環(huán)境變量倉庫里只放占位符。第三個(gè)坑是自動(dòng)同步覆蓋了手工補(bǔ)充。用了轉(zhuǎn)換器后腳本會(huì)把整個(gè)目錄重建手工維護(hù)的備注被沖掉過一次。后來我把自動(dòng)生成的頁面和手工維護(hù)頁面放在不同目錄腳本只處理帶自動(dòng)生成標(biāo)記的目錄。第四個(gè)坑是文檔看起來全但沒講清。打開頁面接口路徑、參數(shù)類型都有但沒有示例值、沒有枚舉含義前端依然要在群里問。這屬于內(nèi)容規(guī)范問題不是工具問題解決方法是把 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)限、目錄、成員管理完善無權(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% 的問題。工具換得越頻繁團(tuán)隊(duì)對(duì)文檔必須更新的敬畏感越低。6.3 我給正在入門的人三條建議第一條先部署再談規(guī)范。把 ShowDoc 跑起來手動(dòng)維護(hù)兩個(gè)接口試試手感比空想一個(gè)月都有效。第二條接入自動(dòng)同步前先把 Swagger 注解補(bǔ)完整否則自動(dòng)化推上去的也是垃圾內(nèi)容。第三條接受 ShowDoc 的不完美它不是一個(gè)在線調(diào)試器它是團(tuán)隊(duì)的知識(shí)庫你需要讓它展示內(nèi)容而不是承擔(dān)所有接口工具的角色。我現(xiàn)在團(tuán)隊(duì)里的日常流程就是Spring Boot 代碼就是規(guī)范SpringDoc 負(fù)責(zé)生成 OpenAPI JSON轉(zhuǎn)換器負(fù)責(zé)把 JSON 變成 ShowDoc 頁面CI 負(fù)責(zé)在發(fā)布后自動(dòng)同步前端在 ShowDoc 上看文檔、在協(xié)作群里接收變更通知。如果你也準(zhǔn)備把 ShowDoc 引入團(tuán)隊(duì)別追求一步到位。先把服務(wù)跑起來找兩個(gè)真實(shí)接口維護(hù)出示例然后讓前端把 Word 扔掉再慢慢加自動(dòng)化。工具永遠(yuǎn)不是重點(diǎn)重點(diǎn)是團(tuán)隊(duì)愿不愿意把接口信息當(dāng)成代碼的一部分去維護(hù)。