spring cloud 整合swagger 3.0 生成接口文档

1.引入swagger3.0相关依赖

        
            io.springfox
            springfox-boot-starter
            3.0.0
        

2.创建swagger配置类

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                //资源
                .globalResponses(HttpMethod.GET, new ArrayList<>())
                .globalResponses(HttpMethod.PUT, new ArrayList<>())
                .globalResponses(HttpMethod.POST, new ArrayList<>())
                .globalResponses(HttpMethod.DELETE, new ArrayList<>())
                //是否启动
                .enable(true)
                //头部信息
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                //过滤某个路径
                .paths(PathSelectors.any())
                .build()
                //协议
                .protocols(newHashSet("https", "http"))
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }
    
    /**
     * API 页面上半部分展示信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .description("@author LiuYong")
                .contact(new Contact("LiuYong", null, "[email protected]"))
                .version("1.0")
                .build();
    }

    /**
     * 设置接口单独的授权信息
     */
    private List securitySchemes() {
        return Collections.singletonList(new ApiKey("BASE_TOKEN", "token", "header"));
    }

    /**
     * 授权信息全局应用
     */
    private List securityContexts() {
        return Collections.singletonList(
                SecurityContext.builder()
                        .securityReferences(
                              Collections.singletonList(new SecurityReference("BASE_TOKEN",
                                        new AuthorizationScope[]{new AuthorizationScope("global", "")}
                                )))
                        //.forPaths(PathSelectors.any())
                        .build()
        );
    }

@SafeVarargs
    private final  Set newHashSet(T... ts) {
        if (ts.length > 0) {
            return new LinkedHashSet<>(Arrays.asList(ts));
        }
        return null;
    }
}

3.创建swagger资源类

@Component
@Primary
public class SwaggerProvider implements SwaggerResourcesProvider {

    @Autowired
    private RouteLocator routeLocator;

    /**
     * 网关应用名称
     */
    @Value("${spring.application.name}")
    private String self;

    @Override
    public List get() {
        List resources = new ArrayList<>();
        List routeHosts = new ArrayList<>();
        routeLocator.getRoutes()
                .filter(route -> route.getUri().getHost() != null)
                .filter(route -> Objects.equals(route.getUri().getScheme(), "lb"))
                //过滤掉网关自身的服务  uri中的host就是服务id
                .filter(route -> !self.equalsIgnoreCase(route.getUri().getHost()))
                .subscribe(route -> routeHosts.add(route.getUri().getHost()));
        // 记录已经添加过的server，存在同一个应用注册了多个服务在注册中心上
        Set set = new HashSet<>();
        routeHosts.forEach(instance -> {
            // 拼接url ，请求swagger的url
            String url = "/" + instance.toLowerCase() + CommonConstant.SWAGGER2URL;
            if (!set.contains(url)) {
                set.add(url);
                SwaggerResource swaggerResource = new SwaggerResource();
                swaggerResource.setUrl(url);
                swaggerResource.setName(instance);
                resources.add(swaggerResource);
            }
        });
        return resources;
    }
}

注意事项：

• swagger3默认的url后缀 ：  SWAGGER2URL = "/v3/api-docs"

4.添加注解

•     @EnableOpenApi：启动类上添加此注解，使swagger生效
•     @Api：类上添加此注解，注明此类的功能
•     @ApiOperation：方法上添加此注解，注明此方法的功能

5.添加swagger插件注解

        
        
            com.github.xiaoymin
            knife4j-spring-boot-starter
            3.0.3
        

6.访问swagger3.0文档

• 访问地址：ip:port/doc.html