| Driven by the community, Springfox3.0 was released in July last year, and recently I finally had time to chat with my friends about the new changes in the new version. This version upgrade is estimated to have been waiting for a long time. After all, the last time the version was released was two years ago. |
Driven by the community, Springfox3.0 was released in July last year, and recently I finally had time to chat with my friends about the new changes in the new version. This version upgrade is estimated to have been waiting for a long time. After all, the last time the version was released was two years ago.
The new version still has a lot of fun, let's take a look.
Support OpenAPI
What is OpenAPI?
The OpenAPI specification is actually the previous Swagger specification. It is a description format of REST API, which describes the document interface through established specifications. It is the industry's true API document standard and can be described by YAML or JSON. It includes the following:
Interface (/users) and each interface operation (GET /users, POST /users)
input parameters and response content
Authentication method
Some necessary contact information, license, etc.
For more information about OpenAPI, interested friends can view it on GitHub: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md
rely
When using version 2.9.2 in the past, generally speaking, we may need to add the following two dependencies:
<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>
Of these two, one is used to generate interface documents (JSON data), and the other is used to visualize JSON.
In version 3.0, we don't need to be so troublesome, a starter can do it:
<dependency>
<groupid>io.springfox</groupid>
<artifactid>springfox-boot-starter</artifactid>
<version>3.0.0</version>
</dependency>
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.
interface address
The interface address in 3.0 is also different from before. In 2.9.2, we mainly visited two addresses:
Document interface address: http://localhost:8080/v2/api-docs
Document page address: http://localhost:8080/swagger-ui.html
Now in 3.0, these two addresses have also changed:
Document interface address: http://localhost:8080/v3/api-docs
Document page address: http://localhost:8080/swagger-ui/index.html
Especially the document page address, if you use 3.0, go to visit The previous page will report 404.
The old annotations can still be used, but some other annotations are also provided in 3.0.
For example, we can use @EnableOpenApi instead of @EnableSwagger2 in the previous version.
That's how it is said, but in actual experience, Song Ge feels that the function of @EnableOpenApi annotation is not obvious. You can add it or not. Turning over the source code, the main function of @EnableOpenApi annotation is to import the OpenApiDocumentationConfiguration configuration class, as follows:
@Retention(value = java.lang.annotation.RetentionPolicy.RUNTIME)
@Target(value = {java.lang.annotation.ElementType.TYPE})
@Documented
@Import(OpenApiDocumentationConfiguration.class)
public @interface EnableOpenApi {
}
Then I looked at the automation configuration class OpenApiAutoConfiguration, as follows:
@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 {
}
As you can see, OpenApiDocumentationConfiguration is also imported into the automation configuration class.
So under normal circumstances, there is actually no need to add @EnableOpenApi annotations.
According to the definition in the @ConditionalOnProperty conditional annotation on OpenApiAutoConfiguration, we found that if springfox.documentation.enabled=false is set in application.properties, the swagger function is turned off. At this time, the automatic configuration class will not be executed. At this time, you can pass @EnableOpenApi annotation imports the OpenApiDocumentationConfiguration configuration class. Technically speaking, the logic is like this, but such a requirement has not been found in the application yet (ie, turn off swagger in application.properties, and then turn it on through the @EnableOpenApi annotation).