还在用 Swagger？试试这款神器，功能真心强大！

Posted 2021-10-23 Java技术栈

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了还在用 Swagger？试试这款神器，功能真心强大！相关的知识，希望对你有一定的参考价值。

介绍

smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具，smart-doc在业内率先提出基于JAVA泛型定义推导的理念，完全基于接口源码来分析生成接口文档，不采用任何注解侵入到业务代码中。

你只需要按照java-doc标准编写注释， smart-doc就能帮你生成一个简易明了的Markdown、html5、Postman、Collection2.0+、OpenAPI 3.0+的文档。

目前使用者

科大讯飞
小米
一加
顺丰

特点

零注解、零学习成本、只需要写标准JAVA注释。
基于源代码接口定义自动推导，强大的返回结构推导。
支持Spring MVC、Spring Boot、Spring Boot Web Flux(controller书写方式)、Feign。
支持Callable、Future、CompletableFuture等异步接口返回的推导。
支持JavaBean上的JSR303参数校验规范，包括分组验证。
对JSON请求参数的接口能够自动生成模拟JSON参数。
对一些常用字段定义能够生成有效的模拟值。
支持生成JSON返回值示例。
支持从项目外部加载源代码来生成字段注释(包括标准规范发布的jar包)。
支持生成多种格式文档：Markdown、HTML5、Asciidoctor、Postman Collection、OpenAPI 3.0。Up- 开放文档数据，可自由实现接入文档管理系统。
支持导出错误码和定义在代码中的各种字典码到接口文档。
支持Maven、Gradle插件式轻松集成。
支持Apache Dubbo RPC接口文档生成。
debug接口调试html5页面完全支持文件上传，下载(@download tag标记下载方法)测试。

Smart-doc 从 2.0.0 后几乎实现了 swagger ui 的功能，并且比 swagger ui 更简洁大方，也更符合国内开发者的诉求。

当然 smart-doc 本身是只支持扫描代码生成 openapi 3.0 的文档的，也可以将生成的 openapi 3.0 文档导入到其他ui中渲染展示。

效果示例

1.1 接口文档效果图

输入图片说明

请求参数示例

响应参数示例

1.2 html全局效果

更多了解，开源地址：https://gitee.com/smart-doc-team

近期热文推荐：

1.1,000+ 道 Java面试题及答案整理(2021最新版)

2.别在再满屏的 if/ else 了，试试策略模式，真香！！

3.卧槽！Java 中的 xx ≠ null 是什么新语法？

4.Spring Boot 2.5 重磅发布，黑暗模式太炸了！

5.《Java开发手册（嵩山版）》最新发布，速速下载！

觉得不错，别忘了随手点赞+转发哦！

还在用Swagger？我推荐这款零代码侵入的接口管理神器！

静态的 Swagger 们跟不上频繁变更的代码

“为什么改了这个没告诉我”,“实际功能和文档上说的不一样啊”。这些话大家做开发的想必耳朵都听出老茧了。真不是故意的，有时候任务比较急，就先改了代码，想着以后再同步文档，然后就给忘了。项目更新又全靠社交软件通知，人一多难免有一两个没及时沟通到的。确实给合作的小伙伴带来麻烦，但说实话开发也挺委屈的。

这些问题产生的主要原因是，当前大部分研发团队的工作流程是这样的：

旧协作模式

这种模式带来的问题是：
1. Swagger ，postman ，MockJS 只能完成软件研发流程中某个环节的功能，造成完成接口设计，文档编写，调试，测试验证等工作需要使用好几个工具；
2.更麻烦的是这些工具数据格式不互通，无法互相导入，造成用 Swagger 定义和编写完成接口后，在 Postman， MockJS ， Jmeter 等工具还要再去手动填写一遍才能开始工作，增加了无意义的工作量。
3.沟通成本总是被忽略不计，但实际上不仅占据了很大时间，各种沟通不及时、沟通不到位还非常让人心累。
4.老板的需求来得急，老板的需求变得快，各种代码修改和变更难以及时通知和同步到团队成员手中。

抱怨当然政治正确，但有啥用，该加的班还是要加。那么有什么办法可以解决这个问题吗？

有的。

换个工具。

低成本做长期主义的事情

我为大家提供的解决方案是一款国内的生产力工具—— Apifox 。

作为一款研发全流程，接口全周期的生产力工具，这款软件真正完成了数据流的打通，在一个软件上就能实现接口设计—接口文档—接口调试—接口修改—接口 mock —接口测试—接口自动化—接口迭代的工作流闭环；
后端，前端，测试各个角色既能各取所需，又能协同合作。

Apifox 上的协作流程是这样的：

后端在 Apifox 可视化接口设计界面上定义好项目各个接口及对应参数同时编写接口文档说明
前后端一起评审，修改完善接口并在同一界面顺手更新接口文档
后端使用接口调试功能调试接口
前端使用零配置高仿真 mock 功能对前端页面进行调试，无需手写 mock 规则
后端使用代码生成功能直接生成接口代码
测试在接口管理页面一键生成接口参数测试用例,并依据业务场景生成自动化测试用例，一键运行接口用例并生成接口测试报告并分享给相关人员。
前后端 都开发完，前端从 Mock 数据切换到正式数据，进行联调，由于使用同一个接口数据源，且遵循了接口规范，联调顺利
由于bug 修复或需求变更，接口发生了变化，后端修改提交后，前端和测试实时同步到了修改后的数据
项目经理通过权限设置给研发,产品,测试,外部合作人员分配编辑,只读等各种操作权限，维护了项目安全
项目经理通过各个接口的状态开发中,测试中,已发布来跟进项目的进度情况，把控项目风险。

Apifox 核心功能和界面是这样的：

接口设计

接口调试

智能 mock

接口自动化

36氪报道过， Apifox 在 Pre-A 轮融资就得到了 3000 万元的融资。资本市场如此看好这个产品的发展潜力，是因为在经济增速变缓的现阶段，

对企业来说，它能通过提高整体的合作效率来为企业节约成本；
对研发人员来说，可以减少无意义的工作量和繁杂耗时的沟通成本，将时间花在能提升自身竞争力的地方。

Apifox > Swagger + Postman + mockJS + Jmeter ，它在传统软件的基础上做了不少操作优化和团队协同提效的功能。

Apifox 做的增速提效优化

1.接口设计：从代码生成界面到可视化接口设计界面
Apifox 接口文档遵循 OpenApi 3.0 (原 Swagger )、 JSON Schema 规范，可生成在线文档；零学习成本即可编写出符合 RESTful 风格的接口文档，新人上手快；所见即所得，不易出错。

Swagger 通过写代码生成接口页面

Apifox 可视化接口设计页面

2.文档维护：从接口与文档分离到接口与文档合并
当你接手旧项目时，发现接口是上周的，接口文档是商周的，上手新项目全靠老司机口口相传，内心大概是崩溃的吧。
接口与文档分离常常导致维护困难。Apifox 的接口设计界面提供了 Markdown 格式的文档说明区，修改完接口就如同 commit 代码时添加变更说明般，自然而然地形成肌肉记忆。

接口设计页面提供了接口文档说明区

3.数据复用：从各自为政到定义一次、多次复用
接口数据复用：Swagger ，Postman ，MockJS ，Jmeter 等软件彼此之间数据不互通，数据格式不一致，接口导入非常耗时麻烦。
而 Apifox 能身兼多职，包揽上述软件功能，在 Apifox 中定义一次接口，能被后端直接用来调试，前端直接用来 mock 界面，测试直接执行接口自动化。
数据模型复用：可复用的数据结构，定义接口返回数据结构及请求参数数据结构（仅 JSON 和 XML 模式）时可直接引用。

定义数据模型

引用数据模型

4.同步更新，高效沟通:从沟通滞后到数据变更即时同步
当前团队成员之间同步项目信息数据，仍旧依靠着社交软件，低效、不及时，也容易漏掉某些成员。
Apifox 为此提供了同步功能，一旦接口数据有更新发生，就会即时同步更新并通知到项目内所有成员。

5.零配置 mock 高仿真数据:从苦逼造数据到零配置 mock 真实数据
Apifox 根据接口定义里的数据结构、数据类型，自动生成 mock 规则。Apifox 内置智能 mock 规则库，根据字段名、字段数据类型，智能优化自动生成的 mock 规则。
用户还可以自定义规则库，满足各种个性化需求。支持使用正则表达式、通配符来匹配字段名自定义 mock 规则。