企业官网建设流程全解析

1. 项目概述与核心价值

我最早接触 ShowDoc，是几年前在某公司做内部接口整理。当时团队里后端、前端、测试各用各的工具，前端看设计稿猜字段，测试拿 Postman 集合点来点去，后端只有一段注释残缺的代码，每个人对接口的理解都不一样。直到有人把 ShowDoc 引入到项目里，我才真正体会到"接口文档工具"和"接口文档平台"的差别有多大。

这次分享的"Spring Boot API 接口文档 ShowDoc 从入门到精通"这个主题，看似是个工具链的拼接，但实际做下来，核心解决的问题就三个——规范接口描述、打通前后端沟通、让文档保持鲜活。

ShowDoc 是一款开源的 API 文档管理工具，适合做团队内部的知识沉淀和接口管理。它支持通过 Markdown 编写文档，也提供了类似 Postman 的调试功能，最实用的一点是，它可以直接部署到内网，不依赖任何外部服务，接口数据全部存在自己的服务器上，很多团队选择它的第一个理由往往就是这个——数据不出内网，安全可控。

和 Swagger 这类代码即文档的框架不同，ShowDoc 更偏向"文档平台"的定位。Swagger 通过注解自动生成文档，好处是代码和文档天然同步，坏处是侵入性强、文章结构难自定义；ShowDoc 则是"手动维护 + 自动化导入"并行的路线，灵活度更高，也更容易组织出清晰的项目级目录结构。

适合谁来参考这篇文章？如果你是后端开发、前端开发、测试工程师，或者技术团队的管理者，正在为接口沟通效率低、文档过期快、新成员上手慢发愁，那么这篇文章的核心思路和实操方案可以直接拿来用。

2. Spring Boot 与 ShowDoc 整合的整体设计思路

2.1 为什么选择 ShowDoc 而不是直接用 Swagger

这个问题当初在团队里讨论了很久。Swagger 有它的天然优势——Spring Boot 项目只需引入依赖，加几个注解，文档就能自动生成，接口参数、返回结构、错误码都能从代码里扫出来，省力是真的省力。

但 Swagger 也有明显的短板。第一，文档的结构受限于代码结构，想按业务域重新编排文档目录基本做不到；第二，接口文档的补充描述、业务流程说明、调用方注意事项这类"非代码信息"没有合适的地方放；第三，Swagger UI 的交互体验偏开发向，测试和产品同学用起来并不顺手。

ShowDoc 恰好补上了这些空缺。文档可以按项目、按目录自由组织，Swagger 风格的接口列表能自动生成，也能兼容 OpenAPI 格式导入，还可以用 Markdown 写详细的业务说明、流程图、版本更新记录。对于需要"代码内外结合"的团队场景，ShowDoc 是比 Swagger 更完整的方案。

不过这里想提醒一点，ShowDoc 并不是要替代 Swagger，而是互补。实际项目中，我见过很多团队两种都用——Swagger 负责在线调试，ShowDoc 负责沉淀文档和流程说明，两边各司其职。

2.2 整合方案的三种路线对比

在 Spring Boot 项目中接入 ShowDoc，大体上有三条路线，我帮大家梳理一下各自的适用场景。

我通常的建议是：第一步先用 springdoc 导出 OpenAPI JSON 生成基础文档，然后在 ShowDoc 里补充业务层面的说明和流程信息，最后根据团队习惯决定是否接上自动推送。这样既有自动化效率，又不丢失文档的"人工温度"。

2.3 这套整合方案能解决哪些实际问题

把 Spring Boot 和 ShowDoc 整合好，收益是肉眼可见的。

首先是"文档过期"问题。接口改了参数，Spring Boot 里的注解同步修改，OpenAPI JSON 一导出，ShowDoc 的文档马上就能更新，不用再追着后端同事问"这个接口现在还返不返回那个字段"。

其次是"信息孤岛"问题。ShowDoc 支持多项目、多目录，可以把前端、后端、测试、运维相关的文档都放在一个平台上，按项目分组管理，新成员入职后直接去 ShowDoc 上看文档，比自己翻代码、问同事高效得多。

第三是"排查问题慢"的问题。ShowDoc 提供了接口调试页面，可以直接填参数、发请求、看返回，测试和开发各自都能快速定位问题，不需要反复在聊天工具里传截图。

这三类问题的解决，本质上都是降低了信息在不同角色之间流动的成本。接口文档不再是一份静态的文件，而是一个团队协作的基础设施。

3. ShowDoc 部署与基础配置

3.1 服务端快速部署

ShowDoc 官方提供了 Docker 镜像，部署非常简单。我自己第一次部署的时候，从下载到页面能访问，前后不超过十分钟。

如果使用 Docker 部署，命令大致如下：

# 创建数据目录 mkdir -p /opt/showdoc/data # 启动 ShowDoc 容器 docker run -d --name showdoc \ -p 4999:80 \ -v /opt/showdoc/data:/var/www/html/ \ --restart=always \ showdoc/showdoc:latest

部署完成后，浏览器访问http://服务器IP:4999，首次打开会要求设置管理员账号。这里有个细节值得注意，数据目录必须挂载宿主机，否则容器一旦重建，所有文档数据都会丢失，这个坑我踩过一次。

如果不方便用 Docker，也可以直接用 PHP 环境部署。ShowDoc 是基于 PHP 开发的应用，官方提供了源码包，放到 Web 服务器的根目录即可，PHP 版本建议 7.2 以上。不过我始终觉得 Docker 方式更干净，升级、备份都方便。

3.2 初始化配置与团队权限管理

部署好后，建议第一时间做三件事：创建团队、设置成员角色、开启 API 密钥。

ShowDoc 的权限模型分为管理员、编辑者、访客三种角色。管理员可以管理项目和成员；编辑者可以新建、修改文档；访客只能查看。实际使用中，我通常会让开发人员担任编辑者，测试同学也是编辑者，产品和其他协作角色统一只开放访客权限。

API 密钥要单独说一句。ShowDoc 提供了开放接口，可以调用 API 来创建项目、更新文档，自动化推送文档靠的就是这个密钥。在每个项目的"项目设置"里可以生成专属的api_key和api_token，后面自动化推送会用到。

还有一个小建议：如果团队人数超过五人，不要用共用的账号来管理文档，每个人都用自己的账号登录，这样文档的修改历史才清晰，出问题了能追溯。

3.3 项目目录结构的设计思路

ShowDoc 的项目内部可以分成多个目录，目录层级支持两级，足够应付大多数场景。目录设计直接影响文档的可用性，我实践中常用的分层方式是这样的：

• 一级目录按业务模块划分，比如"用户模块""订单模块""支付模块"；
• 二级目录按接口类型划分，比如"查询接口""操作接口""回调接口"；
• 每个接口条目内部，再按照"接口描述""请求参数""返回参数""错误码""调用示例"五个部分组织。

这样的结构看起来简单，但对于几百个接口的项目来说，维护成本会大幅降低。找接口的时候，先知道属于哪个业务模块，再知道是查询还是操作，基本能秒定位到具体条目。

4. Spring Boot 集成与自动化导入实战

4.1 在 Spring Boot 项目中集成 springdoc

要在 Spring Boot 中导出 OpenAPI 格式的 JSON，最常用的做法是集成 springdoc-openapi。这是一个非常成熟的库，对 Spring Boot 2.x 和 3.x 都有对应的版本支持。

以 Spring Boot 2.x 为例，在pom.xml中加入依赖：

<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.7.0</version> </dependency>

启动项目后，访问http://localhost:8080/v3/api-docs，就能看到 OpenAPI 格式的 JSON 文档。如果配套引入了springdoc-openapi-ui，还能直接访问http://localhost:8080/swagger-ui.html，用 Swagger UI 在线调试接口。

这里有一个关键的配置点。Spring Boot 的接口很多时候统一加了前缀，比如/api/v1，如果不配置，生成的文档里路径也会带上这个前缀，ShowDoc 导入后看起来会有点乱。我一般会在application.yml里加一段配置：

springdoc: api-docs: path: /v3/api-docs swagger-ui: path: /swagger-ui.html packages-to-scan: com.example.project.controller paths-to-match: /api/**

packages-to-scan指定扫描哪个包下的控制器，paths-to-match限定哪些路径进入文档，相当于给文档划了一个边界，避免把无关端点扫进去。

4.2 写好注解是文档质量的关键

springdoc 能自动扫到 Spring MVC 的@RestController和@RequestMapping，但如果不写补充注解，生成的文档里只有路径和参数名，描述信息基本都是空的。想让文档真正可读，必须在代码里把注解写到位。

我通常会在每个 Controller 类上写@Tag，给模块起个清晰的名字；每个接口方法上写@Operation，描述这个接口的业务含义；每个参数上写@Parameter，说明参数的含义、是否必填、示例值。

举一个简单的例子：

@RestController @RequestMapping("/api/user") @Tag(name = "用户模块", description = "用户信息查询与维护接口") public class UserController { @GetMapping("/info") @Operation(summary = "获取用户信息", description = "根据用户ID获取用户基本信息，仅查询启用状态的用户") public Result<UserInfoVO> getUserInfo( @Parameter(description = "用户ID", required = true, example = "10001") @RequestParam Long userId) { // 业务逻辑略 } }

这些注解写得越完整，后面导入 ShowDoc 的文档就越充实。经验不足的同学容易忽略example字段，但实际测试同学最在意的就是这个示例值，有了它才能直接在调试页面上点发送。

4.3 通过 OpenAPI JSON 导入 ShowDoc

拿到 OpenAPI JSON 后，导入 ShowDoc 有两种方式。一种是在线导入，登录 ShowDoc 后台，在项目中找到"导入文档"功能，选择 OpenAPI 格式上传 JSON 文件；另一种是调用 ShowDoc 提供的 API 接口，用代码或脚本自动导入。

在线导入适合一次性初始化，自动导入适合日常持续同步。实际操作中，我推荐把自动导入做成一个脚本，放进项目的构建流程里，这样每次代码改动跑一遍构建，文档就同步更新了。

ShowDoc 的 API 导入接口大概是这样的形式：

curl -X POST http://showdoc服务器地址/server/api/openapi/import \ -H "Content-Type: multipart/form-data" \ -F "api_key=项目API密钥" \ -F "api_token=项目API令牌" \ -F "openapi_json=@openapi.json"

其中openapi.json是从 Spring Boot 的/v3/api-docs导出的 JSON 文件。只要调通一次，后续就可以把这条命令固化在 CI 构建脚本里，实现文档的自动同步。

4.4 自动化推送的完整配置流程

如果想实现"构建就更新文档"，我建议用 ShowDoc 官方提供的 Maven 插件或自行封装 HTTP 调用。以 Maven 插件为例，在pom.xml的build节点中配置插件，指定目标 ShowDoc 地址和项目密钥，然后执行mvn package时插件会自动推送文档。

插件的核心配置参考如下：

<plugin> <groupId>com.showdoc</groupId> <artifactId>showdoc-maven-plugin</artifactId> <version>1.0</version> <configuration> <showdocUrl>http://showdoc服务器地址</showdocUrl> <apiKey>项目的api_key</apiKey> <apiToken>项目的api_token</apiToken> <openapiJsonPath>target/openapi.json</openapiJsonPath> </configuration> </plugin>

这个方案的隐藏价值在于"文档随代码走"。开发改完接口，Jenkins 或 GitLab CI 跑一次构建，OpenAPI JSON 自动生成并推送到 ShowDoc，整个链条几乎不需要人工干预。我用了几个月后最大的感受是：文档和代码不同步的问题，终于从根上解决了。

不过也要提醒，插件方式对多分支开发不太友好。多个分支同时开发时，构建产物可能来自不同分支，会互相覆盖文档。我们团队的做法是，只在主分支构建时触发文档推送，其他分支不推送，从流程上避免覆盖。

5. ShowDoc 进阶使用技巧

5.1 用 Markdown 大幅提升文档可读性

ShowDoc 里除了接口文档，还支持 Markdown 类型的文档页面。这一块功能非常容易被忽略，但实际上价值巨大。

我通常会在每个项目下放几个固定的 Markdown 页面："项目说明"、"接口规范"、"更新日志"。项目说明里写清楚这个项目是做什么的、依赖哪些服务、联调环境地址是什么；接口规范里写清楚命名规则、参数格式约定、统一返回结构；更新日志就按时间线记录每次接口变更的说明。这些信息放在代码里没人看，放在公告里会沉底，放在 ShowDoc 项目里，每个访问文档的人都能看到。

Markdown 页面还支持插入图片和代码块，可以用它在文档里放流程图、时序图、代码示例。对前端同学来说，文档里有可直接复制的请求示例代码，比对着接口描述自己拼代码效率高得多。

5.2 拥抱 OpenAPI 生态，打通更多工具链

ShowDoc 支持兼容 OpenAPI 格式的导入导出，这意味着它不是一个封闭的"文档孤岛"，而是能融入更大的 API 工具生态。

举个例子，你可以用 Apifox 或 Postman 先调试接口，确认无误后导出 OpenAPI JSON，再导入 ShowDoc 作为正式文档。反过来，ShowDoc 中的接口也可以导出为 OpenAPI JSON，供其他工具使用。这种互通性让我在实际项目里能灵活组合工具链，不会因为用了 ShowDoc 就被绑死在某一种工作流里。

还有一个小场景是接口测试。ShowDoc 支持在线调试，但有些复杂的测试场景（比如依赖登录态的接口）不如专用测试工具方便。我的建议是：ShowDoc 负责"静态文档 + 快捷调试"，复杂测试回到 Postman 或 Apifox，两边通过 OpenAPI 无缝衔接。

5.3 团队协作机制与文档规范落地

工具永远是辅助，真正的瓶颈在习惯和规范。ShowDoc 用了一段时间后，我最深的体会是：如果没有明确的文档维护规则，再好的工具也会慢慢变成垃圾场。

我建议团队里至少确立三条规则。第一，接口文档必须在接口上线前写好，联调前必须确认文档已更新；第二，接口变更必须同步修改文档，并更新"更新日志"页面，不允许悄悄改接口；第三，每周安排一次文档巡查，检查是否存在文档缺失、描述不清晰、信息过期的情况。

这三条规则看起来简单，但确实能有效避免"文档现象级过期"的问题。工具只是提供了可能性，真正让文档发挥作用的是团队一致的行动。

6. 常见问题与排查技巧实录

6.1 Docker 部署后页面打不开的排查思路

这种情况十有八九是端口映射或防火墙的问题。先确认容器是否正常运行：docker ps看一下容器状态，再执行docker logs showdoc查看日志。如果容器是Exited状态，多半是启动过程中的权限问题或者端口冲突。

端口冲突最常见的现象是容器一直重启，比如宿主机上已经有服务占了 4999 端口。换一个端口重新映射就好。防火墙方面，云服务器还需要在安全组里放行对应端口，这个很多人会漏掉。

6.2 OpenAPI JSON 导入后接口分组混乱

导入 ShowDoc 后，接口的默认分组是根据@Tag注解生成的。如果 Controller 里没有写@Tag，所有接口都堆在"默认分组"里，导入后文档自然看起来杂乱无章。

解决思路很简单：逐个 Controller 补充@Tag注解，按业务模块命名，重新导出 JSON 再导入。如果接口特别多，写个脚本批量检查哪些 Controller 缺少@Tag，这是效率最高的方式。

6.3 springdoc 生成的 JSON 过大，导入超时

接口数量几百个以上，或者返回结构特别复杂时，JSON 文件可能达到几 MB，导入 ShowDoc 时会超时或失败。处理办法有三个：一是减少扫描范围，在配置中把paths-to-match收紧，分批导入；二是导入前对 JSON 做压缩或瘦身，只保留必要字段；三是改用 API 方式导入，配合脚本超时重试。

这个问题的底层原因是 ShowDoc 服务端的导入处理能力有限，所以从源头控制 JSON 大小才是治本之策。

6.4 自动化推送偶尔失败的应对方案

自动化推送和网络、权限、服务状态都有关联，偶尔失败很正常。我在实践中总结了一套处理顺序：先检查 ShowDoc 服务是否正常，再检查api_key和api_token是否有效，最后看脚本日志里的返回信息。

ShowDoc 的 API 正常返回会有明确的error_code字段，根据这个字段基本能定位问题。比如返回10001通常是参数缺失，返回10003通常是权限不正确，具体对应关系在官方接口文档有说明。排查熟练之后，这类问题五分钟内就能解决。

6.5 编写规范的过程化心得

在我实际使用的过程中，关于如何把 ShowDoc 的效果发挥到最大，有几点体会很深刻。

一个是"文档写给别人看"的立场。写参数描述时，不要站在后端角度写"userId"，而要站在调用方角度写清楚"用户ID，由创建用户接口返回，必填"。用消费视角来撰写文档，沟通效率会明显不一样。

另一个是"文档需要持续喂养"。自动化导入只是解决了"接口结构同步"的问题，业务描述、调用场景、注意事项这些依然需要开发人员主动维护。把文档维护当成开发工作的一部分，而不是额外负担，才能真正形成良性循环。

最后一个小技巧是，在 ShowDoc 项目里专门建立一个"接口变更记录"目录，每次重要变更都新建一条 Markdown 文档，记录变更时间、变更内容、影响范围、责任人。几个月后回头翻看，整个项目的接口演进脉络一目了然，无论是排查历史问题，还是做系统重构，都能派上大用场。

这个内容是后续扩展的一个好方向。比如可以在 ShowDoc 的文档基础上，结合代码生成工具，把接口文档自动转成前端 TypeScript 类型定义和请求封装代码，或者转成后端的接口校验规则。文档从"给人看的说明"进化成"驱动多端代码生成的中枢"，这才是接口文档工具链更深一层的价值。