swagger20和21的区别（swagger2和3）

科技前沿 • 2025-04-20 18:16 • 阅读 50

大家好，我是讯享网，很高兴认识大家。

在SpringBoot3 中集成 Swagger 接口文档，如果按照网上的很多提示，会有些问题。在这个过程中我就遇到报错：

Caused by: java.lang.ClassNotFoundException: javax.servlet.http.HttpServletRequest

因为最新的 SpringBoot3 里javax命令空间有变化，而 Swagger 已经停更。经过调试我这边成功的配置和示例如下：

1. 引入的包为 springdoc-openapi-starter-webmvc-ui

之前测试一些常用的 swagger-annotations

讯享网

2. application.yaml中的相关配置

讯享网

3. Swagger3中的 SwaggerConfig 类如下

4. Swagger3 中使用的注解

Swagger2 和 Swagger3 使用注解区别很大，基本完全变了。

Swagger2                    Swagger3
@Api                            @Tag
@ApiOperation            @Operation
@ApiImplicitParams   @Parameters
@ApiImplicitParam      @Parameter
@ApiModel                  @Schema
@ApiModelProperty @Schema
@ApiResponses @ApiResponses
@ApiResponse            @ApiResponse
@ApiIgnore                  @Hidden

主要使用的也就是 Tag 和 Parameter 注解。放在 controller的方法上标识接口。如下为我一个测试控制器的方法如下：

讯享网

5. 业务控制器中的方法注解如下：

此处只用于测试，接口方法均先返回的 Listmap数据。尚未使用 json 包处理。示例如下：

讯享网

如上，SpringBoot3 集成的 Swagger3 接口文档实际上是用的 springdoc-openapi-starter-webmvc-ui , 网上很多集成 swagger 的多是 Springfox 的，因此没法参考使用。通过上面的这些配置处理，展示的页面效果如下：

在使用 springdoc-openapi-starter-webmvc-ui 的时候，发现有二个问题未实现。

一是实现的对接口的排序，在 Swagger2 里有一个 order 链式方法可以使用，但在这里我试了试，只发现在springdoc yaml 配置中有一个 writer-with-order-by-keys 。其值有 true/false/on/off ,尝试了一下都不能达到的我预期。设置为true/false 其会按字母倒序、顺序展示，但一不能实现直接按控制器中的接口方法顺序排列，也未看到哪里有自定义的顺序参数。

二是对于接口页面其页面的 title/description/keywords 未找到哪里可以进行设置。有些在yml配置中追加开启了 Knife4j 增强，但我对于目前的 Swagger 其它都满意，就只有这两个点没有找到方法。如果有朋友发现了这两个问题的解决方法，欢迎在评论中告诉我，感谢！