SpringDoc2问题汇总

在项目中尝试使用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());

后续有更好或者更优雅的办法再考虑考虑。

秒客网