What has been updated in Swagger 3 compared to Swagger 2, and what optimizations have been made? Swagger 3 interpretation

Article Directory

What has been updated in Swagger 3 compared to Swagger 2, and what optimizations have been made? Swagger 3 interpretation


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

Related Reading OpenAPI Specification
Related Reading Swagger- Magically modified version of bootstrap swagger UI page, springboot integrates
Related Reading Swagger2-Build a basic Swagger2Configuration interface, reduce class error rate and complexity
Related Reading based on Swagger2 Build Restfu API online documentation and test the interface
Related Reading Use Swagger2 to build document content

Portal

Portal Swagger official website address

Process Support OpenApi


OpenApi It is a description format of REST API, which describes the document interface through established specifications. It is the real API document standard in the industry and can be described through YAML or 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

For details, please refer to OpenAPI Specification

Process Provide a more convenient form of dependency


The Swagger 3 version only needs a starter dependency to complete the introduction

<dependency>
    <groupid>io.springfox</groupid>
    <artifactid>springfox-boot-starter</artifactid>
    <version>3.0.0</version>
</dependency>

Before Swagger 3 version, you need two

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

In addition, like other starters in Spring Boot, springfox-boot-starter relies on zero configuration
and automatic configuration support. In other words, if you have no other special requirements, just add a dependency, and the interface documentation will be automatically generated

Process Change of interface address


The interface address of the Swagger 3 version is

Document interface address: http://localhost:8080/v3/api-docs
document page address:http://localhost:8080/swagger-ui/index.html

The interface address before Swagger 3 version is

Document interface address: http://localhost:8080/v2/api-docs
document page address:http://localhost:8080/swagger-ui.html

The interface address between the versions is not compatible, access to the old address will 404

Process Annotation changes


The old annotations before the Swagger 3 version can continue to be used, and some additional annotations have been added

@EnableOpenApiInstead of before @EnableSwagger2
, but this may not add annotation, because Swagger 3 were automatically configured, the following code can be seen particularly

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

}

Note that OpenApiDocumentationConfigurationboth positions are imported

We can springfox.documentation.enabled=falseturn off Swagger 3

Process Docket changes


Swagger 3 version needs to set the document information type to OAS_3, before Swagger 3 version it isSWAGGER_2


Reference

Reference Resources Swagger documentation

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