@[toc]

Swagger 3 对比于 Swagger 2 更新了哪些内容，做了哪些优化 ？Swagger 3 解读

---

如果觉得本文对你有帮助，可以一键三连支持，谢谢

相关阅读

Related Reading OpenAPI Specification

Related Reading Swagger - 魔改版本的 bootstrap swagger UI 页面 ，springboot 集成

Related Reading Swagger2 - 构建一个基本的 Swagger2Configuration 的接口，降低类的出错率和复杂性

Related Reading 基于Swagger2构建Restfu API在线文档并进行接口的测试

Related Reading 使用Swagger2构建文档内容

传送门

---

Portal Swagger 官网地址

Process 支持 OpenApi

---

OpenApi 是一种 REST API 的描述格式，通过既定的规范来描述文档接口，它是业界真正的 API 文档标准，可以通过 YAML 或者 JSON 来描述

OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API, including:

Available endpoints (/users) and operations on each endpoint (GET /users, POST /users)

Operation parameters Input and output for each operation

Authentication methods

Contact information, license, terms of use and other information.

API specifications can be written in YAML or JSON. The format is easy to learn and readable to both humans and machines. The complete OpenAPI Specification can be found on GitHub: OpenAPI 3.0 Specification

具体了解可以参考 OpenAPI Specification

Process 提供更方便的依赖形式

---

Swagger 3 版本只需要一个 starter 依赖即可完成引入

<dependency>

    <groupid>io.springfox</groupid>

    <artifactid>springfox-boot-starter</artifactid>

    <version>3.0.0</version>

</dependency>

Swagger 3 版本之前则需要两个

<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>

另外，和 Spring Boot 中的其他 starter 一样，springfox-boot-starter 依赖可以实现零配置

以及自动配置支持。也就是说，如果你没有其他特殊需求，加一个这个依赖就行了，接口文档就自动生成了

Process 接口地址的变化

---

Swagger 3 版本的接口地址为

文档接口地址：http://localhost:8080/v3/api-docs

文档页面地址：http://localhost:8080/swagger-ui/index.html

Swagger 3 版本之前的接口地址为

文档接口地址：http://localhost:8080/v2/api-docs

文档页面地址：http://localhost:8080/swagger-ui.html

版本之间接口地址没有兼容，访问旧的地址会 404

Process 注解的变化

---

Swagger 3 版本之前旧的注解可以继续使用，另外额外新增了一些注解

@EnableOpenApi 代替了之前的 @EnableSwagger2

但是这个注解可以不加，因为 Swagger 3 进行了自动配置，具体可以看如下代码

@Retention(value = java.lang.annotation.RetentionPolicy.RUNTIME)

@Target(value = {java.lang.annotation.ElementType.TYPE})

@Documented

@Import(OpenApiDocumentationConfiguration.class)

public @interface EnableOpenApi {

}

@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 两个位置都导入了

我们可以通过 springfox.documentation.enabled=false 来关闭 Swagger 3

Process Docket 的变化

---

Swagger 3 版本需要把文档信息类型设置为 OAS_3，Swagger 3 版本之前则是 SWAGGER_2

---

参考资料

Reference Resources Swagger 文档

本文地址 https://wretchant.blog.csdn.net/article/details/117769859

博客地址 https://wretchant.blog.csdn.net/