Swagger 3.0 天天刷屏，真的香吗？

持续原创输出,点击上方蓝字关注我

目录

前言

官方文档如何说？

Spring Boot版本说明

添加依赖

springfox-boot-starter做了什么？

撸起袖子就是干？

定制一个基本的文档示例

文档如何分组？

如何添加授权信息？

如何携带公共的请求参数？

粗略是一个BUG

总结

前言

最近频繁被Swagger 3.0刷屏，官方表示这是一个突破性的变更，有很多的亮点，我还真不太相信，今天来带大家尝尝鲜，看看这碗汤到底鲜不鲜....

官方文档如何说？

该项目开源在Github上，地址：https://github.com/springfox/springfox。

Swagger 3.0有何改动？官方文档总结如下几点：

删除了对springfox-swagger2的依赖

删除所有@EnableSwagger2...注解

添加了springfox-boot-starter依赖项

移除了guava等第三方依赖

文档访问地址改变了，改成了:port/project/swagger-ui/index.html。

姑且看到这里，各位初始感觉如何？

既然人家更新出来了，咱不能不捧场，下面就介绍下Spring Boot如何整合Swagger 3.0吧。

Spring Boot版本说明

作者使用Spring Boot的版本是2.3.5.RELEASE

添加依赖

Swagger 3.0已经有了与Spring Boot整合的启动器，只需要添加以下依赖：

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> springfox-boot-starter做了什么？

Swagger 3.0主推的一大特色就是这个启动器，那么这个启动器做了什么呢？

「记住」：启动器的一切逻辑都在自动配置类中。

找到springfox-boot-starter的自动配置类，在/META-INF/spring.factories文件中，如下：

从上图可以知道，自动配置类就是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 { }

敢情这个自动配置类啥也没干，就光导入了几个配置类(@Import)以及开启了属性配置(@EnableConfigurationProperties)。

3

「重点」：记住OpenApiDocumentationConfiguration这个配置类，初步看来这是个BUG，本人也不想深入，里面的代码写的实在拙劣，注释都不写。

撸起袖子就是干？

说真的，还是和以前一样，真的没什么太大的改变，按照文档的步骤一步步来。

定制一个基本的文档示例

一切的东西还是需要配置类手动配置，说真的，我以为会在全局配置文件中自己配置就行了。哎，想多了。配置类如下：

@EnableOpenApi @Configuration @EnableConfigurationProperties(value = {SwaggerProperties.class}) public class SwaggerConfig { /** * 配置属性 */ @Autowired private SwaggerProperties properties; @Bean public Docket frontApi() { return new Docket(DocumentationType.OAS_30) //是否开启，根据环境配置 .enable(properties.getFront().getEnable()) .groupName(properties.getFront().getGroupName()) .apiInfo(frontApiInfo()) .select() //指定扫描的包 .apis(RequestHandlerSelectors.basePackage(properties.getFront().getBasePackage())) .paths(PathSelectors.any()) .build(); } /** * 前台API信息 */ private ApiInfo frontApiInfo() { return new ApiInfoBuilder() .title(properties.getFront().getTitle()) .description(properties.getFront().getDescription()) .version(properties.getFront().getVersion()) .contact( //添加开发者的一些信息 new Contact(properties.getFront().getContactName(), properties.getFront().getContactUrl(), properties.getFront().getContactEmail())) .build(); } }

@EnableOpenApi这个注解文档解释如下：

Indicates that Swagger support should be enabled. This should be applied to a Spring java config and should have an accompanying '@Configuration' annotation. Loads all required beans defined in @see SpringSwaggerConfig

什么意思呢？大致意思就是「只有在配置类标注了@EnableOpenApi这个注解才会生成Swagger文档」。

@EnableConfigurationProperties这个注解使开启自定义的属性配置，这是作者自定义的Swagger配置。