1. 先理解 ShowDoc 在 Spring Boot 开发里到底是什么角色做后端最烦的事情里维护接口文档绝对能排进前五。我之前在某团队接手一个订单服务代码里接口全有但文档还停留在上一任同事离职前的 Word 版本前端联调时对着旧文档问这个参数明明没传啊我一看代码字段早改名了。就是从那时候开始我把 Spring Boot API 接口文档的维护方式换成了 ShowDoc。这篇东西不是官方教程是我从部署到落地再到团队一起用起来的全过程记录适合正在纠结要不要上文档工具的后端开发也适合刚把 ShowDoc 装起来但不知道怎么接入 Spring Boot 的读者。1.1 ShowDoc 到底是个什么工具ShowDoc 从产品形态上说是一个私有化、可部署的在线文档系统。它最大的特点不是生成接口文档而是什么文档都能往里放。你可以新建一个接口项目用 Markdown 或富文本维护每个接口的 URL、header、请求体、返回示例、错误码也可以另开一个目录把数据库字段字典、环境配置说明、部署手册全部整理进去。对 Spring Boot 项目来说一个好的接口文档工具需要满足三个条件第一能承载自动生成的内容第二能支持团队在线编辑和评论第三能控制访问权限。ShowDoc 恰好三点都占。它不像 Swagger UI 那样只能展示 Swagger 注解生成的结果也不像某些以调试为核心的工具那样只注重能不能调通它更像一个围绕接口资料的内部 Wiki接口信息只是其中一类页面。1.2 和 Word、Swagger UI 的真实对比我在实际项目里用过 Word、Swagger UI、ShowDoc 三种方式体验差别很大。Word 文档的问题是完全没有强约束。谁改了代码不更新 Word没人知道多人同时编辑时版本互相覆盖文档里写详见 XX 文档最后根本找不到。Swagger UI 的问题是能看不能用。它确实能根据注解实时生成接口列表也能在线调试但字段说明、业务含义、错误码意思、数据字典这些靠注解很难写清楚而且一旦项目多了Swagger UI 的导航会变得非常难用还经常遇到跨域问题。ShowDoc 的价值在于把这几种工具的长处合到一起接口列表从 OpenAPI 数据导入字段说明、错误码、更新记录靠编辑页面补充访问权限按项目划分历史版本还能找回。我用下来最直观的感受是前端拿到的不再是一堆 JSON schema而是一份他们自己能看懂的接口使用说明。1.3 哪些项目适合选 ShowDoc不是所有团队都适合。如果是单机小 Demo直接看 Swagger UI 就够如果团队规模很大已经在用一体化 API 管理平台也没必要再引入 ShowDoc。ShowDoc 最合适的场景是接口数量中等几十到几百个、前后端协作流程还没完全规范化、需要把接口文档放在公司内网、还需要有人能编辑权限的团队。我现在的团队就是用 Spring Boot 做微服务每个服务一个工程ShowDoc 按服务建项目实践了半年效果比之前好太多。2. 部署 ShowDoc 服务我推荐私有化 Docker 方案ShowDoc 官方提供在线版但介于接口文档通常带有业务信息我不太建议把公司内部接口丢给第三方。私有化部署是最稳妥的选择而 Docker 方案最省心。2.1 一条命令跑起来如果你服务器上已经装好 Docker启动 ShowDoc 其实就是一句命令docker run -d \ --name showdoc \ --restartalways \ -p 4999:80 \ -v /data/showdoc_data:/var/www/html/ \ showdoc/showdoc这条命令做了三件事把容器命名为 showdoc方便后续查看日志和启停用--restartalways保证服务器重启后容器自动拉起把宿主机的/data/showdoc_data目录挂载到容器 Web 根目录这样文档数据不会随容器删除而丢失。启动完成后访问http://服务器IP:4999走完初始化引导用默认管理员账号登录并立即改掉密码。这里特别提醒默认端口 80 被很多人挂在公网上扫到过建议改成不常用端口再配合防火墙只放行内网 IP 访问。2.2 数据备份恢复的完整做法ShowDoc 的数据存在 MySQL 和文件目录里容器化部署后这些底层细节被隐藏了我们只要保证挂载目录安全就行。我的备份策略很简单每天凌晨压缩整个挂载目录保留最近 7 天。tar -czf /backup/showdoc_$(date %F).tar.gz -C /data showdoc_data find /backup -name showdoc_* -mtime 7 -exec rm -f {} \;恢复操作也直接新服务器上把备份文件解压到同样的/data目录再跑一遍 docker run 命令数据就回来了。我踩过一次坑是早期没意识到挂载目录的重要性升级容器时直接删了容器数据全丢。后来所有 docker run 都带上-v挂载这个教训比任何配置都重要。2.3 项目和权限规划要提前做ShowDoc 安装好后第一件事不是写接口而是规划项目结构。我建议按服务域建项目比如用户服务、订单服务、商品服务而不是把所有接口混到一个项目里。一个项目对应一个 ShowDoc 项目权限好控制文档也好维护。在 ShowDoc 后台项目可以设置为私有项目然后手动添加成员。角色我习惯只开两种后端主程是编辑者其他人是只读成员。前端同学一般不需要编辑权限他们需要的只是稳定的只读地址。如果遇到要临时修改文档的情况再提升权限避免误操作污染文档。这一步看似简单但对后面的自动化同步很关键因为权限规划直接决定 API Key 的使用范围。3. Spring Boot 接入 ShowDoc核心是把 Swagger JSON 变成同步任务ShowDoc 有一个很实用的能力对外开放接口允许你把外部系统生成的文档内容直接写入指定项目。这就给 Spring Boot 项目提供了一个自动化方案用 SpringDoc 生成 OpenAPI JSON再把 JSON 转成 ShowDoc 需要的页面结构最后通过 ShowDoc 开放接口推送上去。3.1 为什么中间格式选 OpenAPI 而不是直接手写市面上很多人误以为用 ShowDoc 就等于放弃 Swagger。实际上两者是配合关系。Spring Boot 项目里通过注解维护接口信息SpringDoc 会自动生成/v3/api-docs的 OpenAPI JSON。这个 JSON 是标准格式包含接口路径、方法、参数、响应体和说明。ShowDoc 支持导入 OpenAPI 格式数据也支持用开放接口创建页面。我之所以选择 OpenAPI 作为中间层是因为它两边不吃亏开发时用注解IDE 能检查文档更新时由脚本把 JSON 转换推送不用人去一个个复制参数。如果哪一天团队决定换文档工具OpenAPI JSON 还能继续导入别的平台数据不会被绑死。3.2 Spring Boot 侧配置 SpringDoc在 Spring Boot 工程里加入 springdoc-openapi 依赖后它自动扫描 Controller 上的注解。下面是基础配置springdoc: api-docs: enabled: true path: /v3/api-docs swagger-ui: path: /swagger-ui.html启动项目后访问http://localhost:8080/v3/api-docs能看到一个很大的 JSON这就是 OpenAPI 数据。为了让这个 JSON 内容够完整Controller 类和方法上的注解要写全稍后我会在第四节专门讲字段规范。这里先记住一个原则注解里写清楚的内容会原样进入 ShowDoc注解里没有的内容后面就得靠手工补工作量大得多。3.3 同步服务的核心代码ShowDoc 的开放接口逻辑是准备好 API Key、API Token、项目 ID然后把文档内容 POST 上去。不同部署地址的开放接口路径可能不一样去后台的开放 API页面能看到当前地址对应的示例。我封装的同步服务简化后是这样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 转换成 ShowDoc 的目录和页面结构 // 推荐的做法是遍历 paths 节点 // 每个 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 中的状态失败则抛出异常 } }这个类的重点在Converter.toShowDocPages它负责把 Swagger JSON 里的paths和tags映射成 ShowDoc 页面层级。比如一个用户管理 tag 下有三个接口最终在 ShowDoc 里就是一个用户管理目录下面挂着三个接口页面。转换逻辑不难但要注意几个问题。第一OpenAPI 里同一个 path 可能对应多个 HTTP 方法比如/user/{id}有 GET 和 PUT页面标题要带上[GET]前缀否则同名页面会互相覆盖。第二ShowDoc 的页面内容是 Markdown转换时要把请求体、响应体、参数表转成 Markdown 表格才能保证前端阅读体验。第三不要把所有接口塞到一个页面按接口页面拆分方便单独维护。3.4 触发方式手动按钮 CI 自动同步同步代码写好后触发方式我推荐两个层面。开发阶段写一个 Spring Boot 单元测试或一个ApplicationRunner启动时打一个开关需要时手动调用 sync 方法。发布阶段在 CI 构建脚本里加一段请求让测试通过后自动执行同步。# 假设同步服务本身也暴露了一个受保护的 HTTP 接口 /sync/api-docs curl -X POST http://localhost:8080/sync/api-docs \ -H Content-Type: application/json \ -d {secret:your-sync-token}这里有一个特别容易踩的坑同步接口不要不加保护地暴露到公网。用 ShowDoc 开放接口时API Token 本身是一个高权限凭据任何拿到它的人都能直接修改文档。所以代码仓库里绝对不能提交真实 token要用环境变量注入同步接口也要加一层自己的签名。4. 让文档真正好用接口内容规范比工具选型更重要我见过不少团队工具从 Word 换到 ShowDoc文档还是一团糟。原因很简单工具解决的是放哪不解决写什么。Spring Boot 接口文档要让人愿意看核心是把字段、返回值、错误码这三件事说清楚。4.1 统一返回结构文档里只放一个真实示例很多 Spring Boot 项目用ResultT包一层这没问题但接口文档里最常见的错误是所有接口的返回示例都写成{code:0, message:成功, data:{}}data 里面到底长什么样完全没说。前端拿到这种文档还是得来问你。我的习惯是在 Controller 的注解里直接用具体响应对象让生成的 OpenAPI JSON 里能看到 data 的结构。比如Operation(summary 查询订单详情) GetMapping(/order/{id}) public ResultOrderDetailVO getOrder(PathVariable Long id) { return Result.success(orderService.getDetail(id)); }然后在OrderDetailVO的每个字段上写Schema(description 订单状态0-待支付1-已支付2-已取消)。这样 Swagger JSON 里的字段说明完整同步到 ShowDoc 后前端就能直接看到 data 结构而不是一个空的{}。4.2 字段说明的五个必填项写字段说明时我要求团队每个字段至少回答五个问题字段名是什么类型是什么string / integer / boolean / object / array是否必传取值范围或枚举含义一个真实可用的示例值。举个例子订单状态如果只写状态两个字前端大概率搞不清楚如果写成订单状态可选值1待支付、2已支付、3已取消示例2联调效率会高很多。这些内容都可以直接写在Schema注解里。需要注意注解里的example属性会进入 OpenAPI JSONShowDoc 转换后也可以保留所以示例值一定要填别嫌麻烦。4.3 错误码单独维护一个页面HTTP 状态码和业务错误码是两码事。很多接口返回 HTTP 200但业务 code 是 10001 表示订单不存在。如果文档里不把业务错误码列清楚前端同事只能靠猜。我在 ShowDoc 项目里固定建一个错误码说明目录用 Markdown 表格维护所有业务 code、含义、建议处理方式。这个目录用脚本自动同步时不要覆盖保留给人工维护。错误码的规范要用排除法所有接口共用一个 code 字段不要某个接口返回success、另一个接口返回status这种不一致是文档大忌。4.4 目录结构要有头脑不要全部堆在顶层ShowDoc 的项目页面是按目录组织的。目录建议按业务模块而不是Controller 类来建。比如订单服务下面分订单查询订单操作售后流程这样前端按业务场景找接口比按类名一个一个翻要快。另外我会给每个模块目录配一个使用说明页面写清楚这个模块的业务背景、通用 header、必填 token、分页规则。这类页面用自动化脚本创建一次就不动了后续手工补充。把自动同步生成的页面和手工维护的页面分开是防止脚本覆盖人工内容的最后一道防线。5. 团队协作中真正提升效率的四个习惯ShowDoc 安装后如果只是一个人上传文档那它只是一个网盘。要让它发挥价值必须把它嵌进团队的工作流里。5.1 访问权限要分清API Key 也要分级别给前端同学分配只读账号而不是把项目链接直接扔到群里让大家匿名访问这是我对团队的最低要求。只读账号的好处是可追溯、可撤销新人进来给他开账号有人离职直接禁用不用换整个项目链接。对自动化同步用的 API Key 也要单独建一个机器人账号不要拿管理员的 Key 去写脚本。这样就算脚本里的 Key 泄露权限只影响指定项目不会波及整个 ShowDoc 服务。这个问题容易被忽视我见过有团队把管理员 token 直接写在前端代码里最后整个文档库都被人清空了。5.2 Mock 数据与并行开发后端接口还没写完时前端最痛苦的是没有数据可以联调。ShowDoc 的页面内容本身就是 Markdown可以在里面维护一份完整的返回示例前端照着示例写死数据先开发页面。等后端好了再切换真实接口大部分逻辑不用改。这个方法比单独搭 Mock 服务更轻量。我在实践中的体会是Mock 服务适合接口数量大、团队已经有一套流程的场景而 ShowDoc 加约定返回示例的方式适合中小团队让前后端先对齐数据结构。关键点在于返回示例必须写的是真实数据结构不能为了示例好看而编一个和实际代码不一致的字段。否则前端按示例写的数据结构到了联调阶段全部要返工比没有 Mock 更糟。5.3 把文档更新动作放进发布流程最容易老化的文档就是没人主动去更新的文档。我现在要求只要后端接口有变更代码合并之前必须把同步脚本跑一遍。这样才能保证线上文档和代码是同一版本。你在 CI 里加一个步骤构建成功后调用同步接口发布没成功文档就不会更新这个联动帮团队省了很多心。CI 脚本里要注意同步接口有网络延迟建议加超时和重试。另外ShowDoc 同步过程是整体更新还是增量更新取决于你转换器的实现我这边是用按目录重建的方式只更新自动生成目录下的页面所以即使同步失败ShowDoc 上还有上一次的旧数据不至于页面全空。5.4 文档变化主动通知不要等前端来问ShowDoc 本身不一定有很复杂的消息通知能力但这不影响我们做变更通知。同步脚本执行成功后可以在最后调用一个通知地址把本次变更的接口清单发给协作群。我习惯在转换器里记录本次变更的路径和方法拼成一段简短文本。这样前端不用天天刷新文档页面看有没有更新后端在群里说一声文档已同步order 模块新增了下单接口大家自然知道。通知逻辑不要放在同步接口内部因为同步接口可能被多次触发应该放在调用方CI 的任务里或者在同步接口返回结果后单独发一次通知。这个细节能避免前端收到重复打扰。6. 两年用下来我遇到的坑和最终建议每个工具都有一套看起来很美的文档但真正的价值藏在坑里。最后这部分全是我的真实经历。6.1 四个最容易让人崩溃的问题第一个坑是升级容器丢数据。我早期用 docker run 部署时没挂载目录后来官方镜像升级我直接把容器删了重建结果所有文档全部清空。解决办法上面写过挂载目录 定时备份双保险。第二个坑是 API Key 泄露。某次代码审查发现同步脚本里的 token 被硬编码在配置文件中而且配置文件不小心被提交到了仓库。虽然事后改了 token但窗口期内知道 token 的人都能改文档很难追责。现在所有密钥一律走环境变量仓库里只放占位符。第三个坑是自动同步覆盖了手工补充。用了转换器后脚本会把整个目录重建手工维护的备注被冲掉过一次。后来我把自动生成的页面和手工维护页面放在不同目录脚本只处理带自动生成标记的目录。第四个坑是文档看起来全但没讲清。打开页面接口路径、参数类型都有但没有示例值、没有枚举含义前端依然要在群里问。这属于内容规范问题不是工具问题解决方法是把 4.2 节五个必填项作为 Code Review 的一部分后端写完接口自己先打开 ShowDoc 看一眼再提交。6.2 和其他方案比ShowDoc 的定位在哪里我不否定其他 API 文档工具但每个工具的侧重点不同。拿我们常用的对比维度看对比维度ShowDocSwagger UI 模式一体化调试管理平台部署成本较低Docker 即可随应用部署较高通常要引入中心化服务自动化程度靠 OpenAPI 转换 开放接口本身自动生成支持多渠道导入在线调试较弱不擅长调试较好直接试接口很强集环境、断言、集合团队协作权限、目录、成员管理完善无权限概念偏平台化适合较大团队私有化方便适合内网随服务内网部署看版本多需商业授权如果你们团队接口数量多到需要集合管理、调试、Mock、自动化测试那一体化管理平台可能是更好的选择。但对大部分中小团队ShowDoc 的轻量、私有化、配合 OpenAPI 自动同步已经能解决 80% 的问题。工具换得越频繁团队对文档必须更新的敬畏感越低。6.3 我给正在入门的人三条建议第一条先部署再谈规范。把 ShowDoc 跑起来手动维护两个接口试试手感比空想一个月都有效。第二条接入自动同步前先把 Swagger 注解补完整否则自动化推上去的也是垃圾内容。第三条接受 ShowDoc 的不完美它不是一个在线调试器它是团队的知识库你需要让它展示内容而不是承担所有接口工具的角色。我现在团队里的日常流程就是Spring Boot 代码就是规范SpringDoc 负责生成 OpenAPI JSON转换器负责把 JSON 变成 ShowDoc 页面CI 负责在发布后自动同步前端在 ShowDoc 上看文档、在协作群里接收变更通知。如果你也准备把 ShowDoc 引入团队别追求一步到位。先把服务跑起来找两个真实接口维护出示例然后让前端把 Word 扔掉再慢慢加自动化。工具永远不是重点重点是团队愿不愿意把接口信息当成代码的一部分去维护。