真的别再用Swagger了,你知道为什么吗?

开发 前端
如果是swagger 的写法,每个字段都要加上 @ApiModelProperty("xxx") 的注解,如果有几十个字段,几十个类,那代码量多的可不小。

哈喽,大家好,我是了不起。

首先,Swagger 这个工具能够自动生成 API 接口文档,在线调试,节省了很多书写文档的时间,非常强大。

但是,想要文档生成的合格,还是要书写大量的注解。有没有一种连注解都不用写的方式呢?

smart-doc简介

今天了不起给大家推荐一个技术:smart-doc,看名字就知道,它是 智能-文档。直接分析代码,根据代码含义生成文档(开个玩笑,它还没有那么智能);其实它是利用的注释,来生成文档,还是需要写注释的。

官方介绍:smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具,smart-doc在业内率先提出基于JAVA泛型定义推导的理念, 完全基于接口源码来分析生成接口文档,不采用任何注解侵入到业务代码中。你只需要按照java-doc标准编写注释, smart-doc就能帮你生成一个简易明了的Markdown、HTML5、Postman Collection2.0+、OpenAPI 3.0+的文档。

swagger和smart-doc的对比

我们来看看swagger和smart-doc的区别

来看看smart-doc 的代码

图片

如果是swagger 的写法,每个字段都要加上 @ApiModelProperty("xxx") 的注解,如果有几十个字段,几十个类,那代码量多的可不小。

不过这些类一般都是自动生成工具生成的,对写代码的人影响不大,不过这样子写倒是简洁了不少,甚得我意~

可能有人就说了,我不写注释,只写swagger注解,看起来也很简洁,这也确实没错。

图片

确实看起来很简洁,不过没有文档注释的情况下,在其他类里你是看不到这个字段的解释的,每次找字段都得回到这个类看看到底是不是这个字段。如果你和同事们的英语都 very good,当我没说。

如果是api接口,smart-doc想要生成文档,需要写成这样(好像看起来什么都没写)

图片

而swagger就需要加上@ApiOperation()这个注解,如果是个参数多的接口,还需要@ApiImplicitParams()这个注解,徒增学习成本

图片

使用smart-doc

总共需要3步:

1.引入pom依赖,是一个插件

<!-- smart-doc插件 -->
<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>${smart-doc-plugin.version}</version>
    <configuration>
        <!--指定生成文档的使用的配置文件-->
        <configFile>${basedir}/src/main/resources/smart-doc.json</configFile>
        <!--指定项目名称-->
        <projectName>${project.name}</projectName>
        <excludes>
            <!--格式为:groupId:artifactId;参考如下-->
            <!--也可以支持正则式如:com.alibaba:.* -->
            <exclude>com.fu:common-.*</exclude>
            <exclude>com.fu:generator</exclude>
        </excludes>
    </configuration>
    <executions>
        <execution>
            <!--如果不需要在执行编译时启动smart-doc,则将phase注释掉-->
            <phase>compile</phase>
            <goals>
                <goal>openapi</goal>
            </goals>
        </execution>
    </executions>
</plugin>

2.编写smart-doc.json文件

{
  // 参考文档:https://smart-doc-group.github.io/#/zh-cn/start/quickstart
  "outPath": "D:\\111",

  "coverOld": true,
  "allInOne": true, // 是否将文档合并到一个文件中,一般推荐为true
  "createDebugPage": true,//@since 2.0.0 smart-doc支持创建可以测试的html页面,仅在AllInOne模式中起作用。
  "isStrict": false, //是否开启严格模式
  // controller包过滤,多个包用英文逗号隔开
  "packageFilters": "com.fu.system.controller.*",
  "projectName": "system",
  "sortByTitle": true, // 接口排序
  "ignoreRequestParams":[ //忽略请求参数对象,把不想生成文档的参数对象屏蔽掉,@since 1.9.2
    "javax.servlet.http.HttpServletRequest",
    "javax.servlet.http.HttpServletResponse",
    "javax.servlet.http.HttpSession"
   ]
}

3.运行这个插件,如果很熟悉mvn命令,在命令行运行它也行;可以生成openapi、postman、html、Markdown等各种格式的文档

图片

关于pom 和 smart-doc.json 的配置,具体配置可前往官方文档查看:

https://smart-doc-group.github.io/#/zh-cn/?id=smart-doc

文档自动化

如果它不能和swagger一样,自动部署文档,还得手动,那也不会来推荐这个了。

官方推荐方式:smart-doc + Torna 

需要额外部署一个 Torna 文档接口服务,类似 yapi;很多企业也都是单独部署的接口文档服务。

可以看出来界面比swagger好太多了

图片

了不起这里给大家另一种方案,本地自动部署,smart-doc + apifox(postman应该也可以)

apifox -> 接口导入 -> 自动同步

图片

图片

这个数据源URL可以直接配置为 file:///D:/111/openapi.json,在你配置pom的时候,直接配置成编译项目时生成 openapi格式的文档,就可以自动部署到apifox,完美~

小结

今天了不起对这个smart-doc就介绍到这里了,感兴趣的小伙伴可以用起来了,对代码0侵入,简直太适合我这种强迫症患者了。

责任编辑:武晓燕 来源: Java技术指北
相关推荐

2023-09-08 08:35:42

层叠样式表CSS

2024-04-03 09:23:31

ES索引分析器

2018-10-28 15:40:23

Python编程语言

2023-03-09 08:23:07

序列化​接口方法

2014-07-15 11:05:30

黑莓

2020-12-07 06:05:34

apidocyapiknife4j

2022-09-28 18:16:34

JavaJDK

2020-12-04 10:05:00

Pythonprint代码

2020-09-03 06:42:12

线程安全CPU

2020-12-02 11:18:50

print调试代码Python

2021-06-09 06:41:11

OFFSETLIMIT分页

2023-10-26 16:33:59

float 布局前段CSS

2021-05-25 09:30:44

kill -9Linux kill -9 pid

2024-04-07 00:00:03

2021-01-29 11:05:50

PrintPython代码

2020-12-15 08:06:45

waitnotifyCondition

2020-12-03 09:05:38

SQL代码方案

2022-09-22 14:55:31

前端JavaScripthis

2022-09-26 13:10:17

JavaScriptthis

2021-02-19 07:59:21

数据埋点数据分析大数据
点赞
收藏

51CTO技术栈公众号