在项目中尝试使用SpringDoc进行文档生成，在使用过程中遇到一系列的问题加以记录.
1.引入依赖
只是单纯的使用SpringDoc的话不需要引入一些乱七八糟的依赖，如今各种增强和拓展依赖层出不穷，但是随着这些依赖的出现带来的不仅是增强，还有各种效率问题。我认为这个还是需要根据个人和项目的需求去进行引入.
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.6.0</version>
</dependency>这个依赖包里包含了SpringDoc和Swagger,可以开箱即用之前用springdoc-openapi-ui,用起来感觉非常难受。
2.Security结合SpringDoc问题
需要SpringSecurity放行部分路径,这里只提供我的参考路径,另外Security方行的问题我会另起一篇来讲.
如果还需要在Swagger中进行调试,需要对OpeanAPI进行一些配置
@Bean
public OpenAPI costomOpenAPI() {
OpenAPI openApi = new OpenAPI().addSecurityItem(new SecurityRequirement().addList("bearerAuth")).components(
new Components()
.addSecuritySchemes(
//这个是自定义的验证名称,用于在对应方法上注解表示使用Security授权调试
"bearerAuth",
new SecurityScheme()
//验证请求方式
.type(SecurityScheme.Type.HTTP)
//验证数据格式
.bearerFormat("JWT")
.in(SecurityScheme.In.HEADER)
//请求头key
.name("Access-Token")
//权限验证方式
.scheme("bearer")
)
).info(costomInfo());
return openApi;
}在代码中的使用:
@PostMapping("/register")
@RequestLimit(coolTime = 60, maxCount = 5)
@Operation(summary = "用户注册(1)", security = @SecurityRequirement(name = "bearerAuth"), description = "用户注册邮箱和密码", requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(required = true, content = @Content(mediaType = "application/json")))
public ResultVO<Boolean> userRegister(
@RequestBody @Valid UserFirstRegisterVO userFirstRegisterVO) {
return userService.userRegister(userFirstRegisterVO);
}3.@RestControllerAdvice拦截SpringDoc返回数据
当使用响应结果处理器时,SpringDoc数据也会被拦截，最好就是将其数据排除在外，也避免对其他包装逻辑的入侵.
@RestControllerAdvice(basePackageClasses = {SpringDocConfig.class})@RestControllerAdvice(basePackages = {"org.springdoc.**"})
4.使用自定义顺序的MessageConverter时,返回数据为Base64字符串.
当我调用 /v3/api-docs接口时，Swagger显示如下:
这段话一开始令我费解，因为依赖包中的版本都是对应的，通过各种问题查询我意识到这应该是Swagger未接收到返回数据,无法展示API界面,后来看到一篇解决文章,然后自己去调试解决了问题,问题文章在此,有兴趣的可以看下 问题文章。
这个问题挺有意思的，我来进行更详细的分析和解决方案.
原因就是调换了MVC原始的报文解析顺序,导致SpringDoc返回的byte[]被Jackson2报文解析器将其解析成了Base64,然后swagger无法解析。
其实知道了问题后,解决的办法有很多很多,我去Git看了原作者给出的解决方案,已经过时了.
1.重写OpenApiResource
其要求继承OpenApiResource,然后将其解析成json格式返回,但是现在返回需为byte[],并且我尝试重写后并没有配置到SpringDoc中,而作者说会自动生效,后续再看看什么情况,或许可以考虑切面对返回值进行转换.
2.添加或调换MessageConverter顺序
出现此问题最根本的原因就是因为调换了MVC中最原始的报文解析顺序,原来应该排在最前的ByteArrayHttpMessageConverter被我放到Jekson2后面去了,但是我不希望因为SpringDoc一个问题而去修改我原来对其他请求的解析顺序，所以重新创建了一个继承ByteArray报文解析器，只需对support进行定义就好，这样就只会对/v3/api-docs返回的byte[]数据进行解析.
public class SpringDocHttpMessageConverter extends ByteArrayHttpMessageConverter {
/**
* 只转换SpringDoc返回的byte[]数据
* @param clazz 其clazz是一个java.util.Collections$SynchronizedSortedMap,无法进行类型比较
* @return true /false
*/
@Override
public boolean supports(Class<?> clazz) {
return byte[].class == clazz && clazz.getName().equals("[B");
}
}
这里Class对象只能去跟byte数组类型进行比较，因为/swagger-config接口去调用时也是通过SpringDoc返回的，但是却返回的是json数据，所以只能通过name去判断是否是/v3/api-docs获取的API数据.
然后将其放在Jekson2前面
//将json转换器排到最前面
converters.add(0, first);
converters.add(0, new SpringDocHttpMessageConverter());后续有更好或者更优雅的办法再考虑考虑。
