微信搜索
江南一点雨

Swagger3.0,你所不知道的新变化!

在社区的推动下,Springfox3.0 去年 7 月份就发布了,最近终于得空和小伙伴们聊一聊新版本的新变化。这次的版本升级估计小伙伴们都翘首以待好久了,毕竟上一次发版已经是两年前的事情了。

新版本还是有很多好玩的地方,我们一起来看下。

支持 OpenAPI

什么是 OpenAPI?

OpenAPI 规范其实就是以前的 Swagger 规范,它是一种 REST API 的描述格式,通过既定的规范来描述文档接口,它是业界真正的 API 文档标准,可以通过 YAML 或者 JSON 来描述。它包括如下内容:

  • 接口(/users)和每个接口的操作(GET /users,POST /users)
  • 输入参数和响应内容
  • 认证方法
  • 一些必要的联系信息、license 等。

关于 OpenAPI 的更多内容,感兴趣的小伙伴可以在 GitHub 上查看:https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md

依赖

以前在使用 2.9.2 这个版本的时候,一般来说我们可能需要添加如下两个依赖:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

这两个,一个用来生成接口文档(JSON 数据),另一个用来展示将 JSON 可视化。

在 3.0 版本中,我们不需要这么麻烦了,一个 starter 就可以搞定:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

和 Spring Boot 中的其他 starter 一样,springfox-boot-starter 依赖可以实现零配置以及自动配置支持。也就是说,如果你没有其他特殊需求,加一个这个依赖就行了,接口文档就自动生成了。

接口地址

3.0 中的接口地址也和之前有所不同,以前在 2.9.2 中我们主要访问两个地址:

  • 文档接口地址:http://localhost:8080/v2/api-docs
  • 文档页面地址:http://localhost:8080/swagger-ui.html

现在在 3.0 中,这两个地址也发生了变化:

  • 文档接口地址:http://localhost:8080/v3/api-docs
  • 文档页面地址:http://localhost:8080/swagger-ui/index.html

特别是文档页面地址,如果用了 3.0,而去访问之前的页面,会报 404。

注解

旧的注解还可以继续使用,不过在 3.0 中还提供了一些其他注解。

例如我们可以使用 @EnableOpenApi 代替以前旧版本中的 @EnableSwagger2。

话是这么说,不过松哥在实际体验中,感觉 @EnableOpenApi 注解的功能不明显,加不加都行。翻了下源码,@EnableOpenApi 注解主要功能是为了导入 OpenApiDocumentationConfiguration 配置类,如下:

@Retention(value = java.lang.annotation.RetentionPolicy.RUNTIME)
@Target(value = {java.lang.annotation.ElementType.TYPE})
@Documented
@Import(OpenApiDocumentationConfiguration.class)
public @interface EnableOpenApi {
}

然后我又看了下自动化配置类 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 {

}

可以看到,自动化配置类里边也导入了 OpenApiDocumentationConfiguration。

所以在正常情况下,实际上不需要添加 @EnableOpenApi 注解。

根据 OpenApiAutoConfiguration 上的 @ConditionalOnProperty 条件注解中的定义,我们发现,如果在 application.properties 中设置 springfox.documentation.enabled=false,即关闭了 swagger 功能,此时自动化配置类就不执行了,这个时候可以通过 @EnableOpenApi 注解导入 OpenApiDocumentationConfiguration 配置类。技术上来说逻辑是这样,不过应用中暂未发现这样的需求(即在 application.properties 中关闭 swagger,再通过 @EnableOpenApi 注解开启)。

对于 @EnableOpenApi 注解的使用场景,小伙伴们要是有自己的见解,欢迎留言讨论。

另外,以前我们用的 @ApiResponses/@ApiResponse 注解,在 3.0 中名字没变,但是所在的包变了,小伙伴们使用时注意导包问题哦。

另外,我们之前用的 @ApiOperation 注解在 3.0 中可以使用 @Operation 代替。

另外还有一些新注解如 @Parameter、Parameters、@Schema 等,松哥尝试了下,感觉不太好用,不如旧的用的舒服,这些新注解小伙伴们可以自行尝试下。

好啦,今天主要和小伙伴们分享了 Swagger3.0 带来的一些新变化,如果还没用过 Swagger,可以在公众号后台回复 666,有一个松哥原创的 Spring Boot 入门教程,里边有讲 Swagger 的用法。

赞(3)
未经允许不得转载:江南一点雨 » Swagger3.0,你所不知道的新变化!
分享到: 更多 (0)
扫码关注微信公众号【江南一点雨】,回复 1024,查看松哥原创 Java 实战教程(图文+视频)。

评论 抢沙发

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址

专注 Java 一百年

关注我们国际站