Springboot 整合swagger2

首先引入依赖

        <!-- Swagger2-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!--浏览方式 swagger-ui   与bootstrap-ui二选一-->
<!--        <dependency>-->
<!--            <groupId>io.springfox</groupId>-->
<!--            <artifactId>springfox-swagger-ui</artifactId>-->
<!--            <version>2.9.2</version>-->
<!--        </dependency>-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

搭建配置文件

package cn.aimanrenjian.orator.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
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.List;

import static com.google.common.collect.Lists.newArrayList;

/***************************
 * 作者: gbing
 * 时间: 
 * 描述: Swagger2配置
 ************************/
@Configuration
@EnableSwagger2
@Profile({"dev","test"}) //设置只在开发环境是生效
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //.apis(RequestHandlerSelectors.basePackage("cn.aimanrenjian.orator.controller"))
                .paths(PathSelectors.any())
                .build()
               .securitySchemes(securitySchemes())
               .securityContexts(securityContexts())  //解决token拦截问题
                .apiInfo(apiInfo());
    }
    //配置一些基本信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("爱满人间接口信息文档")
                .description("接口信息")
                .version("1.0")
                .contact(new Contact("小标题","blog.csdn.net","gbing1995@163.com"))
                .license("The Apache License")
                //.licenseUrl("http://www.baidu.com")
                .build();
    } 
    //解决token拦截问题 配置请求头
    private List<ApiKey> securitySchemes() {
        return newArrayList(
                new ApiKey("oratorUserToken", "oratorUserToken", "header")
                );
    }
    private List<SecurityContext> securityContexts() {
        return newArrayList(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .forPaths(PathSelectors.regex("^(?!auth).*$"))
                        .build()
        );
    }
    //解决token拦截问题 配置参数
    List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return newArrayList(
               // new SecurityReference("Authorization", authorizationScopes),
                new SecurityReference("oratorUserToken", authorizationScopes));
    }
}

涉及拦截问题

@Configuration
public class InterceptorConfig implements WebMvcConfigurer {

  
    //拦截器
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        List<String> userInterceptorUrlList=new ArrayList<>();
        userInterceptorUrlList.add("/**");
        registry.addInterceptor(userVerifyInterceptor())
                .addPathPatterns(userInterceptorUrlList)
                .excludePathPatterns("/user/**", "/swagger-resources/**", "/webjars/**","/v2/**",
                "/swagger-ui.html/**",  //swagger-ui 访问界面
                "/doc.html/**"     //bootstrap访问界面
                );
    }
}

项目访问地址

    swagger-ui 访问界面  :    http://localhost:8092/swagger-ui.html

    bootstrap访问界面   :    http://localhost:8092/doc.html

 

常用注解标识 

注解	属性	值	备注
@Api	value   等同于 ags   description	@Api(value = "xxx", description = "描述")	可用在class头上,class描述
@ApiModel	description	@ApiModel(description= "描述")	可用JavaBean 类上，说明 JavaBean 的 用途
@ApiModelProperty	value required	@ApiModelProperty(value = "名字",required=true)	用在 JavaBean 类的属性上面，说明此属性的的含议
@ApiIgnore		@ApiIgnore()	用于类，方法，方法参数，表示这个方法或者类被忽略，即不会显示在接口文档里面
@ApiOperation	value   notes	@ApiOperation(value = "xxx", notes = "xxx")	可用在方法头上.参数的描述容器
@ApiImplicitParams	@ApiImplicitParam数组	@ApiImplicitParams({@ApiImplicitParam1,@ApiImplicitParam2,...})	可用在方法头上.参数的描述容器
@ApiImplicitParam	name    字符串 与参数命名对应    可用在@ApiImplicitParams里 value    字符串    参数中文描述 allowMultiple 布尔 是否传递多个数字  required    布尔值    true/false dataType    字符串    参数类型  query:对应@RequestParam?传递  path: 对应@PathVariable{}path传递  defaultValue    字符串    在api测试中默认值 paramType    字符串    参数请求方式:query/path header-->请求参数的获取：@RequestHeader query-->请求参数的获取：@RequestParam path（用于restful接口）-->请求参数的获取：@PathVariable body（不常用） form（不常用）	@ApiImplicitParam(name = "id",value = "用户id",allowMultiple=true,required = true,defaultValue = "55")	可用在方法头上.参数的描述容器 表示单独的请求参数，多数时候可以用@ApiParm替代
@ApiResponses	@ApiResponse数组		可用在方法头上.参数的描述容器
@ApiResponse	code       可用在@ApiResponses里 message    字符串    错误描述	@ApiResponse(code = 200, message = "Successful")	@ApiResponses 同@ApiImplicitParams()  用于方法，会在接口文档里面对当前接口返回的信息进行说明