比试一下：Swagger3就是比2简单粗暴

接口文档总是很烦人，我曾经尝试过用Postman来编写和分享项目文档，感觉还不错。但是最近项目紧，我没有额外的时间可以花在它上面，这也导致我尝试YApi(另外一种文档)的计划泡汤了。嗯，目前没有比Swagger更快、更傻瓜的工具，虽然它有严重的代码污染。先拿这个对付一阵时间，等闲暇时间再玩YApi。

创新互联公司专业为企业提供石家庄网站建设、石家庄做网站、石家庄网站设计、石家庄网站制作等企业网站建设、网页设计与制作、石家庄企业网站模板建站服务，十载石家庄做网站经验，不只是建网站，更提供有价值的思路和整体网络服务。

Swagger3集成

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

 
 
 
 

  
  
  
  

  
  
  
  
    io.springfox
  
  
  
  
    springfox-boot-starter
  
  
  
  
    3.0.0
  
  
  
  

 
 
 
 

就这就可以了，简单不?

至于有的教程说还要开启注解@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")
  
  
  
  
                .contact(new Contact("码农小胖哥", "https://felord.cn", "dax@felord.cn"))
  
  
  
  
                .version("1.0.0")
  
  
  
  
                .build();
  
  
  
  
    }
  
  
  
  
}
 
 
 
 

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

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

 
 
 
 

  
  
  
  
@Import(OpenApiDocumentationConfiguration.class)
  
  
  
  
public @interface EnableOpenApi {
  
  
  
  
}
  
  
  
  
@Import(Swagger2DocumentationConfiguration.class)
  
  
  
  
public @interface EnableSwagger2 {
  
  
  
  
}
 
 
 
 

上面的两个导入类都可以在OpenApiAutoConfiguration找到，所以Swagger3提供的是全自动的集成。

和全局统一参数不兼容

如果你使用了统一返回体封装器来标准化Spring MVC接口的统一返回

 
 
 
 

  
  
  
  
/**
  
  
  
  
 * 返回体统一封装器
  
  
  
  
 *
  
  
  
  
 * @author n1
  
  
  
  
 */
  
  
  
  
@RestControllerAdvice 
  
  
  
  
public class RestBodyAdvice implements ResponseBodyAdvice