springboot集成配置swaggerUI

灰太狼 2024-02-19 22:10 78阅读 0赞

##### 1.使用swagger的原因 #####

手写Api文档的几个痛点：

1.  文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
2.  接口返回结果不明确
3.  不能直接在线测试接口，通常需要使用工具，比如postman
4.  接口文档太多，不好管理

##### 2.依赖包配置 #####

<dependency>
    			<groupId>io.springfox</groupId>
    			<artifactId>springfox-swagger2</artifactId>
    			<version>2.7.0</version>
    		</dependency>
    		<dependency>
    			<groupId>io.springfox</groupId>
    			<artifactId>springfox-swagger-ui</artifactId>
    			<version>2.7.0</version>
    		</dependency>

##### 3.配置类 #####

package com.oukingtim.config;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.web.bind.annotation.RestController;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Parameter;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    import java.util.ArrayList;
    import java.util.List;
    
    @Configuration
    @EnableSwagger2
    public class Swagger2Config {
        @Bean
        public Docket createRestApi() {
            List<Parameter> pars = new ArrayList<>();
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                    //.apis(RequestHandlerSelectors.basePackage("方法二：扫描包位置"))
                    .paths(PathSelectors.any())
                    .build()
                    .globalOperationParameters(pars)
                    .apiInfo(apiInfo());
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("刘云生 RESTful API")
                    .description("邮箱：578888218@qq.com")
                    .description("博客地址：https://blog.csdn.net/liuyunshengsir/")
                    .termsOfServiceUrl("https://blog.csdn.net/liuyunshengsir/")
                    .version("1.0")
                    .build();
        }
    }

##### 4.Swagger注解（） #####

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。详细请自行了解

*  @Api：修饰整个类，描述Controller的作用
 *  @ApiOperation：描述一个类的一个方法，或者说一个接口
 *  @ApiParam：单个参数描述
 *  @ApiModel：用对象来接收参数
 *  @ApiProperty：用对象接收参数时，描述对象的一个字段
 *  @ApiResponse：HTTP响应其中1个描述
 *  @ApiResponses：HTTP响应整体描述
 *  @ApiIgnore：使用该注解忽略这个API
 *  @ApiError ：发生错误返回的信息
 *  @ApiImplicitParam：一个请求参数
 *  @ApiImplicitParams：多个请求参数

##### 5.其他 #####

务必将权限拦截排除

#访问地址
    http://localhost:8080/swagger-ui.html

#### 6.统一加入Authorization ####

package com.lys.config;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.*;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spi.service.contexts.SecurityContext;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    import java.util.ArrayList;
    import java.util.Collections;
    import java.util.List;
    /**
     * @Auther: liuysh
     * @Date: 2021/6/26 12:26
     * @Description:
     */
    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
    
        @Bean
        public Docket api() {
            return new Docket(DocumentationType.SWAGGER_2).
                    useDefaultResponseMessages(false)
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.lys.controller"))
                    .paths(PathSelectors.regex("^(?!auth).*$"))
                    .build()
                    .securitySchemes(securitySchemes())
                    .securityContexts(securityContexts())
                    .apiInfo(apiInfo())
                    ;
        }
    
        private List<ApiKey> securitySchemes() {
            List<ApiKey> list =new ArrayList<>();
            list.add(new ApiKey("Authorization", "Authorization", "header"));
            return list;
        }
    
        private List<SecurityContext> securityContexts() {
            return new ArrayList(
                    Collections.singleton(SecurityContext.builder()
                            .securityReferences(defaultAuth())
                            .forPaths(PathSelectors.regex("^(?!auth).*$"))
                            .build())
            );
        }
    
        List<SecurityReference> defaultAuth() {
            AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
            AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
            authorizationScopes[0] = authorizationScope;
            return new ArrayList(
                    Collections.singleton(new SecurityReference("Authorization", authorizationScopes)));
        }
    
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder().title("微服务-XXX api文档").description("restful 风格接口")
                    // 服务条款网址
                    .termsOfServiceUrl("https://blog.csdn.net/liuyunshengsir")
                    .version("1.0")
                    .contact(new Contact("帅呆了", "url", "email"))
                    .build();
        }
    }

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2xpdXl1bnNoZW5nc2ly_size_16_color_FFFFFF_t_70]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2xpdXl1bnNoZW5nc2ly_size_16_color_FFFFFF_t_70]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/29/93db874c8d3e4d9ca5d210d3e8b3009e.png