一、SpringBoot3集成Swagger接口文档功能
在SpringBoot3 中集成 Swagger 接口文档，如果按照网上的很多提示，会有些问题。在这个过程中我就遇到报错：
Caused by: java.lang.ClassNotFoundException: javax.servlet.http.HttpServletRequest
因为最新的 SpringBoot3 里javax命令空间有变化，而 Swagger 已经停更。经过调试我这边成功的配置和示例如下：
1. 引入的包为 springdoc-openapi-starter-webmvc-ui
之前测试一些常用的 swagger-annotations
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.3.0</version>
</dependency>2. application.yaml中的相关配置
springdoc:
api-docs:
path: /v3/api-docs
swagger-ui:
path: /swagger-ui.html
groups-order: desc3. Swagger3中的 SwaggerConfig 类如下
package cn.fangha.config;
import io.swagger.v3.oas.models.OpenAPI;
import org.springframework.context.annotation.Bean;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Configuration;
@Configuration
public class SwaggerConfig {
@Bean
public OpenAPI springOpenAPI() {
return new OpenAPI().info(
new Info().title("信息API接口")
.description("本接口。。。。")
.version("1.0.0")
.summary("summary.")
);
}
}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 包处理。示例如下：
package cn.fangha.controller;
import cn.fangha.services.NormalService;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
@RestController
@Tag(name="API接口大全")
public class LineController {
@Autowired
private NormalService normalService;
@ApiResponse(description = "线路详情")
@Parameter(name = "keychar", description = "线路", required = true)
@GetMapping("/detail/{keychar}")
public Map<String, Object> gaotie_detail(@PathVariable("keychar") String keychar){
Map<String, Object> map = normalService.get_detail(keychar);
return map;
}
}二、Swagger3中的接口排序以及如何设置接口页面的title/keyword/description?
如上，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 其它都满意，就只有这两个点没有找到方法。如果有朋友发现了这两个问题的解决方法，欢迎在评论中告诉我，感谢！
