干掉 Swagger + Postman？测试接口直接生成API文档
优采云 发布时间: 2022-05-09 04:25干掉 Swagger + Postman？测试接口直接生成API文档
② 点击右上角的【+】按钮，我们来新建一个页面，编写一个用户注册的 API 接口文档。
新建页面
③ 点击【API 接口模板】按钮，ShowDoc 会帮我们生成 API 接口文档的示例，采用的是 Markdown 的格式。
API 接口模板
④ 简单修改 Markdown 的内容，然后点击右上角的【保存】按钮，生成文档。
保存接口
⑤ 点击右上角的【返回】按钮，可以看到刚创建的 API 接口文档。
接口预览
在右边，艿艿圈了【分享】【目录】【历史版本】三个按钮，胖友可以自己去体验下。
ShowDoc 提供 API 接口的 Mock 功能，方便后端在定义 API 接口后，提供模拟数据。
① 点击需要 Mock 的 API 接口文档的右边的【编辑页面】按钮，然后点击【Mock】按钮，我们可以看到一个 Mock 的弹窗。
Mock 弹窗
② 填写 Mock 的返回结果，设置 Mock Url 的路径，然后点击【保存】按钮。
设置 Mock
③ 点击【复制】按钮，复制 Mock Url 的路径，然后使用浏览器访问，可以看到 Mock 的返回结果。
请求 Mock 接口
友情提示：ShowDoc 提供的 Mock 能力还是比较基础的，实际项目中，我们可能希望根据不同的请求参数，返回不同的 Mock 结果。
如果胖友有这块需求，可以看看 YApi： 。
通过手写 Markdown 的方式，生成 API 文档的方式，是非常非常非常繁琐 的！！！所以，ShowDoc 自己也不推荐采用这种方式，而是主推 RunApi 工具，一边调试接口，一边自动生成 。
咱先看看 RunApi 的自我介绍，也是贼长一大串：
RunApi 是一个以接口为核心的开发测试工具（功能上类似 Postman）。
目前有客户端版(推荐，支持 Win/Mac/Linux全平台）和在线精简版 ，包含接口测试 / 自动流程测试 / Mock 数据 / 项目协作等功能。
它和 ShowDoc 相辅相成：
相信使用 ShowDoc + RunApi 这两个工具组合，能够极大地提高IT团队的效率。
管你看没看懂，跟着艿艿一起，体验一下就完事了！
① 在 地址下，提供了不同操作系统的 RunApi 客户端的下载。
客户端
② 下载并安装完成后，使用 ShowDoc 注册的账号，进行登陆。
Runapi 登陆
虽然我们在 ShowDoc 中，已经新建了项目，但是我们在 RunApi 中是无法看到的。因此，我们需要重新新建属于 RunApi 的项目。
项目对比
① 点击 RunApi 客户端的【新建项目】按钮，填写项目名和描述，然后点击【确认】按钮进行保存。
新建项目
② 浏览器刷新 ShowDoc 页面，可以看到刚创建的项目。
查看项目
① 点击【+】按钮，选择要新增的类型为“带调试功能的API接口”。
新建 API 接口
② 启动一个 Spring Boot 项目，提供一个需要调试的 API 接口。
友情提示：胖友可以克隆 项目，使用 lab-24/lab-24-apidoc-showdoc 示例。
嘿嘿，顺手求个 Star 关注，艿艿写了 40000+ Spring Boot 和 Spring Cloud 的使用示例代码。
启动 Spring Boot 项目
③ 使用 RunApi 调试下 /users/login 接口。
调试 API 接口
④ 点击【返回示例和参数说明】，补全返回结果的接口文档。
补全响应结果
⑤ 点击【保存】按钮，生成 API 接口文档。
⑥ 点击【文档链接】按钮，获得 API 接口文档的地址。
文档链接
⑦ 点击 API 文档的访问链接，查看 API 文档。
RunAPI 文档预览
当然，我们也可以在 ShowDoc 中，进行访问。
ShowDoc 文档预览
有一点要注意，使用 RunApi 生成的 API 接口文档，无法在使用 Markdown 进行编辑噢！原因也很简单，编写后的 Markdown 文件，可能会导致无法逆向被 RunApi 使用，格式被破坏了！
① 点击需要 Mock 的 API 接口文档的下边的【Mock】按钮，我们可以看到一个 Mock 的界面。
Mock 界面
② 填写 Mock 的返回结果，设置 Mock Url 的路径，然后点击【保存】按钮。
设置 Mock
③ 点击【复制】按钮，复制 Mock Url 的路径，然后使用浏览器访问，可以看到 Mock 的返回结果。
请求 Mock 接口
RunApi 还提供了 3 个高级特性，胖友后面可以自己体验下。
强烈推荐 ！！！
环境变量
例如说，设置“本地环境”、“测试环境”等多套环境变量，方便模拟请求不通过环境下的 API 噢。
前执行脚本
例如说，可以模拟登陆，获得用户的访问 token 令牌。
后执行脚本
例如说，断言响应的结果，是否为期望的 200 。
RunApi 提供的自动 生成 API 接口文档的方式，确实能够避免一部分烦琐 的手写 Markdown 的过程。同时，它能够结合我们日常开发，模拟调用 API 接口的时，复用了请求参数与响应结果。
但是我们如果仔细去思考，这是不是意味着可能此时此刻，我们已经开发完 API 接口了？！那么，假如团队采用的是前后端分离的架构，并且前端和后端是两拨人，那么前端会希望后端提前就定义好 API 接口的文档，而不是在后端具体完成好 API 接口的开发后，再提供接口文档。
所以我们在使用 RunApi 的时候，有可能是先使用它来**“手动”** 定义好 API 接口文档，然后复用它来模拟测试 API 接口。
嘿嘿~胖友也可以思考下，结合 RunApi 的这种模式，怎么结合到我们的日常开发流程中，欢迎留言讨论。
ShowDoc 支持通过扫描代码注释的方式，自动生成 API 接口文档，目前自持 Java、C++、PHP、Node 等等主流的编程语言。
艿艿看了下官方文档 对这块功能的介绍，感受上使用体验会非常不好。一起来看下官方提供的示例：
/**<br /> * showdoc<br /> * @catalog 测试文档/用户相关<br /> * @title 用户登录<br /> * @description 用户登录的接口<br /> * @method get<br /> * @url https://www.showdoc.cc/home/user/login<br /> * @header token 可选 string 设备token <br /> * @param username 必选 string 用户名 <br /> * @param password 必选 string 密码 <br /> * @param name 可选 string 用户昵称 <br /> * @return {"error_code":0,"data":{"uid":"1","username":"12154545","name":"吴系挂","groupid":2,"reg_time":"1436864169","last_login_time":"0"}}<br /> * @return_param groupid int 用户组id<br /> * @return_param name string 用户昵称<br /> * @remark 这里是备注信息<br /> * @number 99<br /> */<br /> public Object login(String username, String password, String name) {<br /> // ... 省略具体代码<br /> }<br />
需要使用到 @catalog、@title 等等自定义的注释标签，且原有的 @param 需要安装一定的格式来保证 API 接口的参数的说明，@return 的示例会导致注释非常长。
自定义注释
这样就导致，虽然只使用代码注释的方式，实际对代码还是有一定的入侵，影响代码的可读性。
还是老样子，我们使用 项目，lab-24/lab-24-apidoc-showdoc 示例，编写一个 users/login2 接口，并使用 ShowDoc 扫码 Java代码注释，生成 API 接口文档。
① 下载 脚本，到项目的根目录。
下载 showdoc_api 脚本
② 在项目的设置页，获得 ShowDoc 的开放 API 的 api_key 和 api_token 秘钥对。
进入项目的设置页获得 api_key 和 api_token 秘钥对
③ 修改 showdoc_api.sh 脚本，设置刚获得的 api_key 和 api_token 秘钥对。
设置 api_key 和 api_token 秘钥对
④ 编写 users/login2 接口，添加 ShowDoc 所需的注释。
编写 users/login2 接口
是不是看着就蛮乱的，IDEA 还报错 @param 找不到 username 和 password 参数。
⑤ 执行 showdoc_api.sh 脚本，扫描 Java代码注释，生成 API 接口文档。
生成 API 接口文档
⑥ 查看生成 API 接口文档。
查看 API 接口文档
如果胖友希望基于 Java 注释生成 API 接口文档，艿艿还是相对 JApiDocs 工具。具体的，可以看看艿艿写的 《芋道 Spring Boot API 接口文档 JApiDocs 入门》 文章。
JApiDocs 效果
ShowDoc 提供给了开放 API 的方式，导入 Markdown 文档。所以，我们可以编写程序，调用它的 API 接口，创建或更新 API 接口文档。
开放 API 的官方文档文档地址是， 。
接口地址 ：
接口参数 ：
接口参数
我们来导入一个简单的文档，效果如下图所示：
{<br /> "api_key": "60fc53cea6af4758c1686cb22ba20566472255580",<br /> "api_token": "0bbb5f564a9ee66333115b1abb8f8d541979489118",<br /> "page_title": "公众号",<br /> "page_content": "芋道源码，求一波关注呀~"<br />}<br />
友情提示：api_key 和 api_token 参数，记得改成自己的秘钥对，不然就导入到艿艿的项目里啦~~~
调用开放 API文档效果
在新建项目时，ShowDoc 支持导入 Swagger 或者 Postman 的 JSON 文档，方便我们快速迁移到 ShowDoc 作为 API 接口的平台。
我们来体验下 ShowDoc 提供的导入 Swagger 文档的功能，使用 项目，lab-24/lab-24-apidoc-swagger-starter 示例，提供的 Swagger JSON 文件。
① 启动 Spring Boot 项目，获得其 Swagger JSON 文件。
下载 Swagger JSON 文件
友情提示：胖友也可以访问 地址，直接进行下载！
② 新建 ShowDoc 项目，点击【导入文件】，选择 Swagger JSON 文件。
导入 Swagger JSON 文件
③ 导入完成后，点击自动新建的项目，查看下导入的 API 文档的效果。
导入 Swagger JSON 文件
接口都成功导入了，可惜 Swagger 中的 example 都缺失了，这就导致我们需要手动补全下接口的示例。
ShowDoc 目前只支持新建项目时，导入 Swagger 接口文档。但是如果 Swagger 接口文档变更时，无法进行更新 ShowDoc 中的文档。
如果我们仅仅是把 Swagger 迁移到 ShowDoc 中，肯定是基本能够满足。但是，如果我们希望使用 Swagger 编写接口文档，手动或者自动导入 ShowDoc 进行展示，这样就无法满足了。
这里艿艿推荐下 YApi 工具，支持定时采集 Swagger 接口，智能 合并 API 接口文档。具体的，可以看看艿艿写的 《芋道 Spring Boot API 接口文档 YApi 入门》 文章。
YApi + Swagger
在上家公司，艿艿就采用 Swagger + YApi 的组合，Swagger 方便后端编写 API 接口文档，YApi 提供接口的展示 、编辑 、Mock 、调试 、自动化测试 。
ShowDoc 支持通过扫描数据库，自动生成表结构的数据库文档。
对应的官方文档地址是， 。
下面， 我们来把艿艿的一个开源项目 的数据库，导入 ShowDoc 生成数据库文档。
① 下载 脚本，并设置数据库相关的参数。
下载 show_db 脚本
② 执行 show_db 脚本，看到“成功”说明成功。查看数据库文档的效果，效果还是还不错。
查看数据库文档
国内还有一款不错的数据库文档的生成工具 Screw，具体可以看看艿艿写的《芋道 Spring Boot 数据表结构文档》，地址是 。
演示效果
至此，我们已经完成 ShowDoc 的入门，还是蛮不错的一个工具。做个简单的小总结：
Talk is Cheap，胖友可以选择动手玩玩 ShowDoc 工具。
- END -
欢迎加入我的知识星球，一起探讨架构，交流源码。加入方式，长按下方二维码噢：
已在知识星球更新源码解析如下：
最近更新《芋道 SpringBoot 2.X 入门》系列，已经 101 余篇，覆盖了MyBatis、Redis、MongoDB、ES、分库分表、读写分离、SpringMVC、Webflux、权限、WebSocket、Dubbo、RabbitMQ、RocketMQ、Kafka、性能测试等等内容。
提供近 3W 行代码的 SpringBoot 示例，以及超 4W 行代码的电商微服务项目。
