swagger3 不能传header未解之谜

最新推荐文章于 2024-07-03 08:49:21 发布

原创最新推荐文章于 2024-07-03 08:49:21 发布 · 6.1k 阅读

7 ·

CC 4.0 BY-SA版权

文章标签：

#ApiIgnore #swagger隐藏参数

java 专栏收录该内容

33 篇文章

订阅专栏

本文分享了在SpringBoot项目中集成Swagger3的过程与心得，包括pom依赖配置、注解使用、解决header参数接收问题及全局认证信息设置。特别讨论了如何处理Authorizationheader的特殊性，提供了解决方案。

刚刚启用swagger3

pom依赖只需要加上 springfox-boot-starter 相当简介

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

然后在启动springboot的启动类增加一个注解，@EnableOpenApi 就OK了。

Controller上增加各种注解，开始直接用的swagger2的注解，一样生效。兼容性不错。

开始swagger3的页面看着还有点不习惯，适应两天就好了。

后面是重点，开始很顺利，遇到一个小问题，获取一个header参数。直接用注解 @RequestHeader 可以收到请求。（用postman）

不用加任何注解，swagger很聪明的识别了这个参数，但是在swagger直接请求接口，提示：

"400 BAD_REQUEST \"Missing request header 'Authorization' for method parameter of type String\""

实在是不解！

后面是各种加注解、调试参数，一样就是无法接收到header参数。

网上查也并没有发现太多类似的文章。

不解～

～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～～

在这条漂亮的分割线以下，找到了问题的所在。

不是swagger的问题，各种配置也都对，问题就在于，参数名！“Authorization” 这个header是用来存认证信息的，因为这次做的也正式认证接口，认证信息从这个header中获取。

结果正常的写法就无法获取这个header了。

swagger是有通用的或者叫做全局的添加认证信息的设置的，就比如你的接口都需要检查token就可以给所以的接口设置统一的token。

具体的开启如下：

    @Bean
    public Docket createRestApi() {
        
        //返回文档摘要信息
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .apis(RequestHandlerSelectors.withMethodAnnotation(Operation.class))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
                //.globalRequestParameters(getGlobalRequestParameters());
                //.globalResponses(HttpMethod.POST, getGlobalResonseMessage());
    }

    private List<SecurityScheme> securitySchemes() {
        List<SecurityScheme> securitySchemes = new ArrayList<>();
        securitySchemes.add(new ApiKey("Authorization", "Authorization", "header"));
        return securitySchemes;
    }

    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.regex("^(?!auth).*$")).build());
        return securityContexts;
    }

    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }

很多地方还没有详细的研究，只是解决了当前的问题，以上代码仅供参考。

同时还引出了另一个问题，如果要从header中获取这个参数，Authorization。不加注解，swagger也会自动给添加一个参数。参数名正是Authorization，不能用，但是不传还提示必填。

所以想取消这个参数，又发现一个小知识点，不想要的参数可以隐藏，在参数前加一个注解 @ApiIgnore

算是比较完美的解决了！