swagger文档配置

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

配置示例

首先引入knife4j依赖

      
        UTF-8
        UTF-8
        1.8
        2.0.2
        5.7.10
       
      
        
            com.github.xiaoymin
            knife4j-spring-boot-starter
            ${knife4j.version}
        

然后创建一个配置类

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)
//                不想使用dcboot中的配置，但是需要添加一个分组，不然会提示重复的Docket对象，
//                 加上分组与dcboot脚手架中的Docket对象进行区分
                .groupName("C3运营端服务接口")
                .apiInfo(apiInfo())
                .select()
                //加了ApiOperation注解的类，才生成接口文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //包下的类，才生成接口文档
                .apis(RequestHandlerSelectors.basePackage("com.dcboot.module"))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }

//    设置spring security oauth2的认证授权的token请求头全局设置
    private List securitySchemes() {
        return newArrayList(
                new ApiKey("Authorization", "Authorization", "header"));
    }
    private List securityContexts() {
        return newArrayList(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .forPaths(PathSelectors.regex("^(?!auth).*$"))
                        .build()
        );
    }
    List 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("C3系统运营端服务")
                .description("C3系统运营端服务Api文档")
//            .termsOfServiceUrl("")
                .version("2.0.0")
                .build();
    }


}

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

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

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

@Slf4j
@SpringBootApplication
@EnableKnife4j
@ComponentScan(value = {"com.dcboot.*"},
        excludeFilters = @ComponentScan.Filter(type = FilterType.ASSIGNABLE_TYPE, classes = SwaggerConfig.class))
public class DcbC3creditOpmInstallApplication {

    public static void main(String[] args) throws UnknownHostException {
        ConfigurableApplicationContext application = SpringApplication.run(DcbC3creditOpmInstallApplication.class, args);
        Environment env = application.getEnvironment();
        String ip = CommonUtil.getInet4Address().getHostAddress();
        String port = env.getProperty("server.port");
        String path = env.getProperty("server.servlet.context-path");
        log.info("http://" + ip + ":" + port + path);
        log.info("swagger接口路径");
        log.info("http://" + ip + ":" + port + path + "/swagger-ui.html");
        log.info("knife4j接口路径");
        log.info("http://" + ip + ":" + port + path + "/doc.html");

        Map map = application.getBeansWithAnnotation(Controller.class);
        System.out.println(map.keySet());
    }

}

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

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

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

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