Shulou(Shulou.com)06/03 Report--

This article mainly introduces "what are the advantages of Swagger3". In daily operation, I believe many people have doubts about the advantages of Swagger3. The editor consulted all kinds of materials and sorted out simple and easy-to-use methods of operation. I hope it will be helpful for you to answer the doubts about "what are the advantages of Swagger3?" Next, please follow the editor to study!

Swagger3 integration

The latest version of Swagger is 3.0.0, and integrating Swagger3 in Spring Boot applications is much easier than the old Swagger2, which provides a Starter component.

Io.springfox springfox-boot-starter 3.0.0

That's it, isn't it?

As for some tutorials that also open the annotation @ EnableOpenApi, there is no need at all. Because you can find a spring.factories under springfox-boot-starter-3.0.0.jar, students who are familiar with Spring Boot all know that this is a Spring Boot-specific SPI file that can automatically discover and register the configuration of Starter components. There is a configuration like this:

# Auto Configure org.springframework.boot.autoconfigure.EnableAutoConfiguration=\ springfox.boot.starter.autoconfigure.OpenApiAutoConfiguration

Follow the steps and find the total configuration class 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 {} some discoveries

We found a key place where the @ ConditionalOnProperty annotation declares that the configuration is enabled when springfox.documentation.enabled is true, and the default value is true. This is very useful, and Swagger only recommends it during the development phase, which happens to be a switch. In addition, sometimes when we customize the configuration, it is best to add this switch:

/ / Custom swagger3 document information @ Configuration @ ConditionalOnProperty (value = "springfox.documentation.enabled", havingValue = "true" MatchIfMissing = true) public class Swagger3Config {@ Bean public Docket createRestApi () {return new Docket (DocumentationType.OAS_30) .apiInfo (apiInfo ()) .select () .apis (RequestHandlerSelectors.withMethodAnnotation (ApiOperation.class)) .build () } private ApiInfo apiInfo () {return new ApiInfoBuilder () .title ("Swagger3 interface document") .description ("more please consult felord.cn") .contact (new Contact ("programmer fat boy", "https://felord.cn",") "dax@felord.cn") .version ("1.0.0") .build () }}

If you want to add Json Web Token to Swagger3, you can refer to this article.

At first we mentioned that Swagger3 does not need to be opened with @ EnableOpenApi or @ EnableSwagger2, and the answer can be found here.

Import (OpenApiDocumentationConfiguration.class) public @ interface EnableOpenApi {} @ Import (Swagger2DocumentationConfiguration.class) public @ interface EnableSwagger2 {}

Both of the above import classes can be found in OpenApiAutoConfiguration, so Swagger3 provides fully automatic integration.

Incompatible with global unified parameters

If you use a unified return wrapper to standardize the unified return of the Spring MVC interface

/ * * author N1 * / @ RestControllerAdvice public class RestBodyAdvice implements ResponseBodyAdvice {@ Override public boolean supports (MethodParameter returnType, Class > converterType) {return! returnType.hasMethodAnnotation (IgnoreRestBody.class);} @ Override public Object beforeBodyWrite (Object body, MethodParameter returnType, MediaType selectedContentType, Class > selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {if (body = = null) {return RestBody.ok () } if (Rest.class.isAssignableFrom (body.getClass () {return body;} return RestBody.okData (body);}}

You will find that Swagger3 will report to Unable to infer base url. This is because the unified return body affects some of Swagger3's built-in interfaces. The solution is @ RestControllerAdvice to control the range of packages that take effect, that is, to configure its basePackages parameters. This potential conflict wasted more than an hour.

Security framework release

If you use a security framework, access to Swagger3's built-in interface will be restricted and we need to rule it out. Spring Security is configured as follows:

@ Override public void configure (WebSecurity web) throws Exception {/ / ignore the static resources needed by swagger3 Allow access to web.ignoring () .antMatchers ("/ swagger-ui.html", "/ swagger-ui/**", "/ swagger-resources/**", "/ v2/api-docs", "/ v3/api-docs", "/ webjars/**") }

If you are using the version Spring Security 5.4, you can customize WebSecurity like this:

@ Bean WebSecurityCustomizer swaggerWebSecurityCustomizer () {return (web)-> {web.ignoring () .antMatchers (new String [] {"/ swagger-ui.html", "/ swagger-ui/**", "/ swagger-resources/**", "/ v2/api-docs", "/ v3/api-docs", "/ webjars/**"});};}

More convenient and simple images, so that Swagger can render and access normally.

At this point, the study of "what are the advantages of Swagger3" is over. I hope to be able to solve your doubts. The collocation of theory and practice can better help you learn, go and try it! If you want to continue to learn more related knowledge, please continue to follow the website, the editor will continue to work hard to bring you more practical articles!

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.