SpringBoot集成Swagger3接口文档及添加Authorization授权

Love The Way You Lie 2024-03-31 17:59 60阅读 0赞

swagger可以为前端提供接口文档及接口测试功能，后端集成起来很方便，对代码也没有入侵，全注解完成，非常好用。

## 一、集成基础功能 ##

### 第一步、添加依赖 ###

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

### 第二步、创建配置文件Swagger3Config ###

### 第三步、给接口添加注解 ###

@Api(tags = "测试不需要登录验证就能访问的接口")
    
    @RestController
    @RequestMapping("/noAuth")
    public class NoAuthController {
    
        /**
         * 服务对象
         */
        private TestService testService;
    
        public NoAuthController(TestService testService) {
            this.testService = testService;
        }
    
        @Operation(summary = "获取test列表数据")
        @RequestMapping(value = "", method = RequestMethod.GET)
        public Page<STest> list(@RequestParam @Parameter(description = "页数从1开始", required = true) int page,
                                @RequestParam @Parameter(description = "每页的条数", required = true) int limit,
                                HttpServletRequest request) {
    
            return testService.list(page - 1, limit);
    
        }
    
    }

Api 给Controller添加的注解

Operation 给Contoller里的方法添加的注解

Parameter 给方法中参数添加的注解

Schema 给实体类及其变量添加的注解

@Schema(description = "test数据")
    @Setter
    @Getter
    public class TestRequestBean {
    
        @Schema(description = "测试字段1")
        private String test;
    
        @Schema(description = "测试字段2")
        private String value;
        
    
    }

访问地址: baseUrl/swagger-ui/index.html

![7d64f0c6cf064fc59d1a1e0f7dfe2ee8.png][]

## 二、让swgger文档支持授权访问 ##

### 修改配置文件，使swagger支持添加token ###

@Configuration
    @EnableOpenApi
    public class Swagger3Config {
    
        @Bean
        public Docket docket() {
            return new Docket(DocumentationType.OAS_30)
                    .apiInfo(apiInfo())
                    .select()
                    // 自行修改为自己的接口路径，不配置扫描全部路径
                    .apis(RequestHandlerSelectors.basePackage("com.by.hellosecurityresource.controller"))
                    .paths(PathSelectors.any())
                    .build()//;
                    .securitySchemes(securitySchemes())
                    .securityContexts(Collections.singletonList(securityContext()));
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("Swagger3 API文档")
                    .description("RESTFul 风格接口")
                    .version("1.0")
                    .build();
        }
    
        private List<SecurityScheme> securitySchemes() {
            List<SecurityScheme> apiKeyList= new ArrayList<>();
            //注意，这里应对应登录token鉴权对应的k-v
            apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));
            return apiKeyList;
        }
    
        /**
         * 这里设置 swagger2 认证的安全上下文
         */
        private SecurityContext securityContext() {
            return SecurityContext.builder()
                    .securityReferences(Collections.singletonList(new SecurityReference("Authorization", scopes())))
                    .build();
        }
    
        /**
         * 这里是写允许认证的scope
         */
        private AuthorizationScope[] scopes() {
            return new AuthorizationScope[]{
                    new AuthorizationScope("web", "All scope is trusted!")
            };
        }
    
    }

### ResourseServer配置中，过滤以下路径，使不通过验证就能访问到，否则无法打开swagger文档 ###

"/swagger-ui/**"
    "/swagger-resources/**"
    "/v3/**"

示例代码如下

@Override
        public void configure(HttpSecurity http) throws Exception {
            http.authorizeRequests()
                    .antMatchers("/noAuth/**", "/swagger-ui/**", "/swagger-resources/**", "/v3/**").permitAll() //设置/oauth/**的接口不需要授权就可以访问
                    .anyRequest().authenticated();
        }

再次访问接口文档，会有此按钮标记

![8bf5e08bd4b0446ab57c14683e38a875.png][]

点击可输入token

![ae9cadd0b0554f0b859df550e5232f46.png][]

这样，在swagger中测试接口的时候就会带上token了。

## 三、生产服务器注意关闭swagger文档 ##

### 在applicaiton中添加配置 ###

springfox:
      documentation:
        auto-startup: false #false关闭swagger文档 true打开swagger

测试代码地址：

[Hello-Security: OAuth2授权服务器][Hello-Security_ OAuth2]

[7d64f0c6cf064fc59d1a1e0f7dfe2ee8.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/31/fe510a7690094c83b6eb0061c82c8072.png
[8bf5e08bd4b0446ab57c14683e38a875.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/31/b5d8b958c01646f0add5f36bcc5af9f1.png
[ae9cadd0b0554f0b859df550e5232f46.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/31/d9c4b3d6bacf4282954699b08b43d52b.png
[Hello-Security_ OAuth2]: https://gitee.com/xiaobailovejiajia/hello-security