swagger文档配置

        swagger文档在springboot项目中使用已经非常广泛，作为api接口管理工具 使用起来也很简单，只需要简单配置一下，就可以生成文档管理页面，在页面上管理查看api接口文档，以及进行接口调试等

配置示例

首先引入knife4j依赖

      <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <java.version>1.8</java.version>
        <knife4j.version>2.0.2</knife4j.version>
        <hutool.version>5.7.10</hutool.version>
       </properties>
      <!--knife4j整合了swagger文档-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>${knife4j.version}</version>
        </dependency>

然后创建一个配置类

import io.swagger.annotations.ApiOperation;
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.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.SecurityReference;
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;

/**
 * @author xiaomifeng1010
 * 配置swagger2
 */
@Configuration("swaggerConfiguration")
@EnableSwagger2
public class SwaggerConfiguration {
    @Bean
    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)

                .groupName("xx服务接口")
                .apiInfo(apiInfo())
                .select()
                //加了ApiOperation注解的类，才生成接口文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //包下的类，才生成接口文档
                .apis(RequestHandlerSelectors.basePackage("com.xiaomifeng1010"))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }

//    设置spring security oauth2的认证授权的token请求头全局设置
    private List<ApiKey> securitySchemes() {
        return newArrayList(
                new ApiKey("Authorization", "Authorization", "header"));
    }
    private List<SecurityContext> securityContexts() {
        return newArrayList(
                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 newArrayList(
                new SecurityReference("Authorization", authorizationScopes));
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xxx服务")
                .description("xxx服务Api文档")
//            .termsOfServiceUrl("")
                .version("2.0.0")
                .build();
    }


}

在配置类上加上@Configuration注解，让spring扫描到，并且识别是一个配置类，然后加上@EnableSwagger2注解，表示启用swagger2

因为项目中用了spring security oauth2做系统的认证，所以在swagger配置中也加入了认证所需的请求头 Authrozation请求头。

最后在启动类上加上@EnableKnife4j,开启swagger增强

@Slf4j
@SpringBootApplication
@EnableKnife4j
public class ABCApplication {

    public static void main(String[] args)  {
        ConfigurableApplicationContext application = SpringApplication.run(ABCApplication .class, args);
      
    }

}

公司自己搞了一个脚手架dcboot，不太好用，虽然脚手架里边已经有swagger2的配置，但是配置的并不友好，所以自定义了配置，需要在启动类中把dcboot中的原来的swagger配置类SwaggerConfig排除

然后访问swagger文档，就会在左侧的菜单中多出来一个Ahthorize的菜单项 

 然后把oauth认证后拿到的token值填入即可，然后调用其他接口就直接可以携带token信息了

如果要让token失效，直接点击注销就可以了，不过一般token都设置了有效期，长时间不操作会自动失效