阅读全文

⭐⭐⭐ Spring Boot 项目实战	⭐⭐⭐ Spring Cloud 项目实战
《Dubbo 实现原理与源码解析 —— 精品合集》	《Netty 实现原理与源码解析 —— 精品合集》
《Spring 实现原理与源码解析 —— 精品合集》	《MyBatis 实现原理与源码解析 —— 精品合集》
《Spring MVC 实现原理与源码解析 —— 精品合集》	《数据库实体设计合集》
《Spring Boot 实现原理与源码解析 —— 精品合集》	《Java 面试题 + Java 学习指南》

摘要: 原创出处 https://www.iocoder.cn/Spring-Boot/ShowDoc/ 「芋道源码」欢迎转载，保留摘要，谢谢！

• 1. ShowDoc 是什么？
• 2. 搭建 ShowDoc
• 3. 快速体验
• 4. RunApi 工具
• 5. 代码注释
• 6. 开放 API
• 7. 导入 Swagger 文档
• 8. 数据库文档
• 666. 彩蛋

---

🙂🙂🙂关注**微信公众号：【芋道源码】**有福利：

1. RocketMQ / MyCAT / Sharding-JDBC 所有源码分析文章列表
2. RocketMQ / MyCAT / Sharding-JDBC 中文注释源码 GitHub 地址
3. 您对于源码的疑问每条留言都将得到认真回复。甚至不知道如何读源码也可以请教噢。
4. 新的源码解析文章实时收到通知。每周更新一篇左右。
5. 认真的源码交流微信群。

---

大家好，我是艿艿，一个在某厂搬砖的小胖子。

之前给大家分享过很多 API 接口文档工具，例如说：

• Swagger：http://www.iocoder.cn/Spring-Boot/Swagger/?1
• knife4j：http://www.iocoder.cn/Spring-Boot/Swagger/?2
• YApi：http://www.iocoder.cn/Spring-Boot/Swagger/?3
• JApiDocs：http://www.iocoder.cn/Spring-Boot/JApiDocs/

昨儿 狗芳 给我推荐了一款新工具 ShowDoc，说是最强国产 API 接口文档工具，可以干掉 Swagger + Postman！

好家伙，这么强的么！搞一波搞一波，白嫖的快乐~

😜 Talk is Cheap，胖友可以选择动手玩玩 ShowDoc 工具。

1. ShowDoc 是什么？

咱先看看 ShowDoc 的自我介绍，贼长一大串：

ShowDoc 是一个非常适合 IT 团队的在线 API 文档、技术文档工具。

通过 ShowDoc，你可以方便地使用 Markdown 语法来书写出美观的 API 文档、数据字典文档、技术文档、在线 Excel 文档等等。

如果不想编辑 Markdown 文档，你还可以利用 ShowDoc 的自动化能力，从程序注释中自动生成 API 文档，或者从搭配的 RunApi 客户端（类似 Postman 的 API 调试工具）中一边调试接口、一边自动生成文档。

通过分配项目成员和团队成员，你可以很方便地进行项目文档的权限管理和团队协作，也可以分享文档出去给朋友查看。

ShowDoc 还支持多平台客户端，有 Win 客户端、Mac 客户端、iOS、Android 等，更方便跨平台使用。目前超过 100000+ 的互联网团队正在使用 ShowDoc，包括知名公司内部的一些团队，比如腾讯、华为、百度、京东、字节跳动等等。

挑咱比较关心的，简单概括下：

1. ShowDoc 是一个在线的 API 文档工具，可以团队多人维护。
2. 提供了三种 API 文档的创建方式：
   • 手动编写 Markdown 文档
   • 基于 Java 代码注释，自动生成。
   • 使用 RunApi 客户端，一边调试接口，一边自动生成。

2. 搭建 ShowDoc

ShowDoc 提供 3 种安装方式：

• Windows 安装：https://www.showdoc.com.cn/help/4087044677189279
• Linux 安装：https://www.showdoc.com.cn/help/828455960655160
• Docker 方式安装：https://www.showdoc.com.cn/help/65610

推荐采用 Docker 或者 Linux 方式来安装，看胖友对 Docker 是否熟悉。😜 艿艿当然是 Docker 安装，都会都会，啊哈哈哈。

不过考虑到快速体验 ShowDoc 的功能，我们直接在 ShowDoc 官方 https://www.showdoc.com.cn/ 注册一个账号体验一下就好啦！

注册完成后，我们可以看到 ShowDoc 提供了 4 个案例。

① API 文档示例

看起来还不错哈~

② 数据字典示例

🙂 就是数据库的表结构~

③ 技术团队文档示例

😎 可以作为简单的 Wiki 文档工具，编写自己团队的技术文档落~

④ 表格工具

简单的在线 Excel 工具，如果团队采用 Excel 管理项目排期，倒是可以体验体验~

3. 快速体验

感受下来，ShowDoc 的功能还是蛮强大的，功能也蛮多的。

下面，我们来新建一个项目，使用 Markdown 文档的方式，撸个 API 接口文档试试。

3.1 新建项目

点击【新建项目】按钮，新建一个属于我们的项目。如下图所示：

友情提示：[导入文件] 这个“高级”功能，咱稍后来演示哈，支持把 Postman 的 JSON 文件、Swagger 的 JSON 文件，导入到 ShowDoc 中，自动生成文档。

3.2 新建 API 接口

① 点击进入项目首页，此时项目还是空的。

② 点击右上角的【+】按钮，我们来新建一个页面，编写一个用户注册的 API 接口文档。

③ 点击【API 接口模板】按钮，ShowDoc 会帮我们生成 API 接口文档的示例，采用的是 Markdown 的格式。

④ 简单修改 Markdown 的内容，然后点击右上角的【保存】按钮，生成文档。

⑤ 点击右上角的【返回】按钮，可以看到刚创建的 API 接口文档。

在右边，艿艿圈了【分享】【目录】【历史版本】三个按钮，胖友可以自己去体验下。

3.3 Mock API 接口

ShowDoc 提供 API 接口的 Mock 功能，方便后端在定义 API 接口后，提供模拟数据。

① 点击需要 Mock 的 API 接口文档的右边的【编辑页面】按钮，然后点击【Mock】按钮，我们可以看到一个 Mock 的弹窗。

② 填写 Mock 的返回结果，设置 Mock Url 的路径，然后点击【保存】按钮。

③ 点击【复制】按钮，复制 Mock Url 的路径，然后使用浏览器访问，可以看到 Mock 的返回结果。

友情提示：ShowDoc 提供的 Mock 能力还是比较基础的，实际项目中，我们可能希望根据不同的请求参数，返回不同的 Mock 结果。

如果胖友有这块需求，可以看看 YApi：http://www.iocoder.cn/Spring-Boot/Swagger/?3 。

4. RunApi 工具

通过手写 Markdown 的方式，生成 API 文档的方式，是非常非常非常繁琐的！！！所以，ShowDoc 自己也不推荐采用这种方式，而是主推 RunApi 工具，一边调试接口，一边自动生成。

4.1 RunApi 是什么？

咱先看看 RunApi 的自我介绍，也是贼长一大串：

RunApi 是一个以接口为核心的开发测试工具（功能上类似 Postman）。

目前有客户端版(推荐，支持 Win/Mac/Linux全平台）和在线精简版 ，包含接口测试 / 自动流程测试 / Mock 数据 / 项目协作等功能。

它和 ShowDoc 相辅相成：

• ShowDoc 以文档为核心，侧重文档编写和知识资料沉淀。
• RunApi 则以接口为核心，包含接口测试、管理、Mock数据、自动化流程测试等一系列功能。同时它将自动生成文档到 ShowDoc，以及共用ShowDoc 的团队管理机制，很好地实现接口的自动化和多人协作。

相信使用 ShowDoc + RunApi 这两个工具组合，能够极大地提高IT团队的效率。

管你看没看懂，跟着艿艿一起，体验一下就完事了！

4.2 下载 RunApi 客户端

① 在 https://www.showdoc.com.cn/runapi/30291 地址下，提供了不同操作系统的 RunApi 客户端的下载。

② 下载并安装完成后，使用 ShowDoc 注册的账号，进行登陆。

4.3 新建项目

虽然我们在 ShowDoc 中，已经新建了项目，但是我们在 RunApi 中是无法看到的。因此，我们需要重新新建属于 RunApi 的项目。

① 点击 RunApi 客户端的【新建项目】按钮，填写项目名和描述，然后点击【确认】按钮进行保存。

② 浏览器刷新 ShowDoc 页面，可以看到刚创建的项目。

4.4 新建 API 接口

① 点击【+】按钮，选择要新增的类型为“带调试功能的API接口”。

② 启动一个 Spring Boot 项目，提供一个需要调试的 API 接口。

友情提示：胖友可以克隆 https://github.com/YunaiV/SpringBoot-Labs 项目，使用 lab-24/lab-24-apidoc-showdoc 示例。

嘿嘿，顺手求个 Star 关注，艿艿写了 40000+ Spring Boot 和 Spring Cloud 的使用示例代码。

③ 使用 RunApi 调试下 /users/login 接口。

④ 点击【返回示例和参数说明】，补全返回结果的接口文档。

⑤ 点击【保存】按钮，生成 API 接口文档。

⑥ 点击【文档链接】按钮，获得 API 接口文档的地址。

⑦ 点击 API 文档的访问链接，查看 API 文档。

当然，我们也可以在 ShowDoc 中，进行访问。

有一点要注意，使用 RunApi 生成的 API 接口文档，无法在使用 Markdown 进行编辑噢！原因也很简单，编写后的 Markdown 文件，可能会导致无法逆向被 RunApi 使用，格式被破坏了！

4.5 Mock API 接口

① 点击需要 Mock 的 API 接口文档的下边的【Mock】按钮，我们可以看到一个 Mock 的界面。

② 填写 Mock 的返回结果，设置 Mock Url 的路径，然后点击【保存】按钮。

③ 点击【复制】按钮，复制 Mock Url 的路径，然后使用浏览器访问，可以看到 Mock 的返回结果。

4.6 高级特性

RunApi 还提供了 3 个高级特性，胖友后面可以自己体验下。

• 环境变量
• 前执行脚本
• 后执行该脚本

4.6.1 环境变量

强烈推荐！！！

例如说，设置“本地环境”、“测试环境”等多套环境变量，方便模拟请求不通过环境下的 API 噢。

4.6.2 前执行脚本

例如说，可以模拟登陆，获得用户的访问 token 令牌。

4.6.3 后执行脚本

例如说，断言响应的结果，是否为期望的 200 。

4.7 思考？

RunApi 提供的自动生成 API 接口文档的方式，确实能够避免一部分烦琐的手写 Markdown 的过程。同时，它能够结合我们日常开发，模拟调用 API 接口的时，复用了请求参数与响应结果。

但是我们如果仔细去思考，这是不是意味着可能此时此刻，我们已经开发完 API 接口了？！那么，假如团队采用的是前后端分离的架构，并且前端和后端是两拨人，那么前端会希望后端提前就定义好 API 接口的文档，而不是在后端具体完成好 API 接口的开发后，再提供接口文档。

所以我们在使用 RunApi 的时候，有可能是先使用它来**“手动”**定义好 API 接口文档，然后复用它来模拟测试 API 接口。

😈 嘿嘿~胖友也可以思考下，结合 RunApi 的这种模式，怎么结合到我们的日常开发流程中，欢迎留言讨论。

5. 代码注释

ShowDoc 支持通过扫描代码注释的方式，自动生成 API 接口文档，目前自持 Java、C++、PHP、Node 等等主流的编程语言。

艿艿看了下官方文档 https://www.showdoc.com.cn/page/741656402509783 对这块功能的介绍，感受上使用体验会非常不好。一起来看下官方提供的示例：

/**
* showdoc
* @catalog 测试文档/用户相关
* @title 用户登录
* @description 用户登录的接口
* @method get
* @url https://www.showdoc.cc/home/user/login
* @header token 可选 string 设备token 
* @param username 必选 string 用户名 
* @param password 必选 string 密码  
* @param name 可选 string 用户昵称  
* @return {"error_code":0,"data":{"uid":"1","username":"12154545","name":"吴系挂","groupid":2,"reg_time":"1436864169","last_login_time":"0"}}
* @return_param groupid int 用户组id
* @return_param name string 用户昵称
* @remark 这里是备注信息
* @number 99
*/
public Object login(String username, String password, String name) {
    // ... 省略具体代码
}

需要使用到 @catalog、@title 等等自定义的注释标签，且原有的 @param 需要安装一定的格式来保证 API 接口的参数的说明，@return 的示例会导致注释非常长。

这样就导致，虽然只使用代码注释的方式，实际对代码还是有一定的入侵，影响代码的可读性。

5.1 快速体验

还是老样子，我们使用 https://github.com/YunaiV/SpringBoot-Labs 项目，lab-24/lab-24-apidoc-showdoc 示例，编写一个 users/login2 接口，并使用 ShowDoc 扫码 Java代码注释，生成 API 接口文档。

① 下载 https://www.showdoc.cc/script/showdoc_api.sh 脚本，到项目的根目录。

② 在项目的设置页，获得 ShowDoc 的开放 API 的 api_key 和 api_token 秘钥对。

③ 修改 showdoc_api.sh 脚本，设置刚获得的 api_key 和 api_token 秘钥对。

④ 编写 users/login2 接口，添加 ShowDoc 所需的注释。

😈 是不是看着就蛮乱的，IDEA 还报错 @param 找不到 username 和 password 参数。

⑤ 执行 showdoc_api.sh 脚本，扫描 Java代码注释，生成 API 接口文档。

⑥ 查看生成 API 接口文档。

5.2 推荐另一个工具

如果胖友希望基于 Java 注释生成 API 接口文档，艿艿还是相对 JApiDocs 工具。具体的，可以看看艿艿写的 《芋道 Spring Boot API 接口文档 JApiDocs 入门》 文章。

6. 开放 API

ShowDoc 提供给了开放 API 的方式，导入 Markdown 文档。所以，我们可以编写程序，调用它的 API 接口，创建或更新 API 接口文档。

开放 API 的官方文档文档地址是，https://www.showdoc.com.cn/page/102098 。

6.1 开放 API 的定义

接口地址：https://www.showdoc.cc/server/api/item/updateByApi

接口参数：

6.2 快速体验

我们来导入一个简单的文档，效果如下图所示：

{
  "api_key": "60fc53cea6af4758c1686cb22ba20566472255580",
  "api_token": "0bbb5f564a9ee66333115b1abb8f8d541979489118",
  "page_title": "公众号",
  "page_content": "芋道源码，求一波关注呀~"
}

友情提示：api_key 和 api_token 参数，记得改成自己的秘钥对，不然就导入到艿艿的项目里啦~~~

7. 导入 Swagger 文档

在新建项目时，ShowDoc 支持导入 Swagger 或者 Postman 的 JSON 文档，方便我们快速迁移到 ShowDoc 作为 API 接口的平台。

7.1 快速体验

我们来体验下 ShowDoc 提供的导入 Swagger 文档的功能，使用 https://github.com/YunaiV/SpringBoot-Labs 项目，lab-24/lab-24-apidoc-swagger-starter 示例，提供的 Swagger JSON 文件。

① 启动 Spring Boot 项目，获得其 Swagger JSON 文件。

友情提示：胖友也可以访问 https://github.com/YunaiV/SpringBoot-Labs/blob/master/lab-24/lab-24-apidoc-showdoc/swagger.json 地址，直接进行下载！

② 新建 ShowDoc 项目，点击【导入文件】，选择 Swagger JSON 文件。

③ 导入完成后，点击自动新建的项目，查看下导入的 API 文档的效果。

接口都成功导入了，可惜 Swagger 中的 example 都缺失了，这就导致我们需要手动补全下接口的示例。

7.2 推荐另一个工具

ShowDoc 目前只支持新建项目时，导入 Swagger 接口文档。但是如果 Swagger 接口文档变更时，无法进行更新 ShowDoc 中的文档。

如果我们仅仅是把 Swagger 迁移到 ShowDoc 中，肯定是基本能够满足。但是，如果我们希望使用 Swagger 编写接口文档，手动或者自动导入 ShowDoc 进行展示，这样就无法满足了。

这里艿艿推荐下 YApi 工具，支持定时采集 Swagger 接口，智能合并 API 接口文档。具体的，可以看看艿艿写的 《芋道 Spring Boot API 接口文档 YApi 入门》 文章。

在上家公司，艿艿就采用 Swagger + YApi 的组合，Swagger 方便后端编写 API 接口文档，YApi 提供接口的展示、编辑、Mock、调试、自动化测试。

8. 数据库文档

ShowDoc 支持通过扫描数据库，自动生成表结构的数据库文档。

对应的官方文档地址是，https://www.showdoc.com.cn/page/312209902620725 。

8.1 快速体验

下面， 我们来把艿艿的一个开源项目 https://github.com/YunaiV/ruoyi-vue-pro 的数据库，导入 ShowDoc 生成数据库文档。

① 下载 https://www.showdoc.cc/script/showdoc_db.sh 脚本，并设置数据库相关的参数。

② 执行 show_db 脚本，看到“成功”说明成功。查看数据库文档的效果，效果还是还不错。

8.2 推荐另一个工具

国内还有一款不错的数据库文档的生成工具 Screw，具体可以看看艿艿写的《芋道 Spring Boot 数据表结构文档》，地址是 http://www.iocoder.cn/Spring-Boot/DB-Doc-screw/?self 。

666. 彩蛋

至此，我们已经完成 ShowDoc 的入门，还是蛮不错的一个工具。做个简单的小总结：

• 从本质上来说，ShowDoc 是一个基于 Markdown 格式的文档工具，支持团队在线协作。
• 通过提供内置的 API 接口模板、数据库文档模板，解决技术团队日常开发中最高频的两个文档需求。
• 通过 RunApi 客户端，提供 API 接口的调试功能。同时，对接 ShowDoc 作为 API 接口平台，最终实现“一边调试，一边生成” API 接口文档的能力。

😜 Talk is Cheap，胖友可以选择动手玩玩 ShowDoc 工具。