碰一碰：Swagger3就是比2简单粗暴

副标题#e#

Swagger目前最新版本是3.0.0,在Spring Boot应用中集成Swagger3比老的Swagger2简单多了，它提供了一个Starter组件。

<dependency> 

    <groupId>io.springfox</groupId> 

    <artifactId>springfox-boot-starter</artifactId> 

    <version>3.0.0</version> 

</dependency> 

就这就可以了，简单不?

至于有的教程说还要开启注解@EnableOpenApi，完全不需要。因为在springfox-boot-starter-3.0.0.jar下你可以找到一个spring.factories，熟悉Spring Boot的同学都知道这个是一个Spring Boot 特有的SPI文件，能够自动的发现并注册Starter组件的配置。里面有这样的配置：

# Auto Configure 

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\ 

springfox.boot.starter.autoconfigure.OpenApiAutoConfiguration 

顺藤摸瓜，找到总的配置类OpenApiAutoConfiguration：

@Configuration 

@EnableConfigurationProperties(SpringfoxConfigurationProperties.class) 

@ConditionalOnProperty(value = "springfox.documentation.enabled", havingValue = "true", matchIfMissing = true) 

@Import({ 

    OpenApiDocumentationConfiguration.class, 

    SpringDataRestConfiguration.class, 

    BeanValidatorPluginsConfiguration.class, 

    Swagger2DocumentationConfiguration.class, 

    SwaggerUiWebFluxConfiguration.class, 

    SwaggerUiWebMvcConfiguration.class 

}) 

@AutoConfigureAfter({ WebMvcAutoConfiguration.class, JacksonAutoConfiguration.class, 

    HttpMessageConvertersAutoConfiguration.class, RepositoryRestMvcAutoConfiguration.class }) 

public class OpenApiAutoConfiguration { 

} 

一些发现

我们找到了关键的一个地方@ConditionalOnProperty注解声明了当springfox.documentation.enabled为true时启用配置，而且默认值就是true。这非常有用，Swagger仅仅建议在开发阶段使用，这个正好是个开关。另外有时候我们自定义配置的时候最好把这个开关也加上：

// 自定义swagger3文档信息 

@Configuration 

@ConditionalOnProperty(value = "springfox.documentation.enabled", havingValue = "true", matchIfMissing = true) 

public class Swagger3Config { 

    @Bean 

    public Docket createRestApi() { 

        return new Docket(DocumentationType.OAS_30) 

                .apiInfo(apiInfo()) 

                .select() 

                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) 

                .paths(PathSelectors.any()) 

                .build(); 

    } 

    private ApiInfo apiInfo() { 

        return new ApiInfoBuilder() 

                .title("Swagger3接口文档") 

                .description("更多请咨询felord.cn") 

#p#副标题#e#

                .contact(new Contact("码农小胖哥", "https://felord.cn", "dax@felord.cn")) 

                .version("1.0.0") 

                .build(); 

    } 

} 

如果你想在Swagger3中加入Json Web Token，可以参考这篇文章。

最开始我们提到Swagger3不需要使用@EnableOpenApi或者@EnableSwagger2开启，这里也能找到答案。