Swagger 3.0 brushes the screen every day. Does it really smell good?

Continuous original output , Click on the blue word above to follow me

Catalog

• Preface
• How to say official documents ？
• Spring Boot Version Description
• New dependencies
• springfox-boot-starter What has been done ？
• Rolling up your sleeves is dry ？

  • Customize a basic file example
  • How files are grouped ？
  • How to add authorization information ？
  • How to carry public request arguments ？
• It's a rough one BUG
• Summary

Preface

Recently, it has been frequently affected by Swagger 3.0 refresh , Officials say it's a breakthrough change , There are a lot of highlights , I don't really believe , Today, I'd like to show you some fresh food , Let's see if the soup is fresh or not ....

How to say official documents ？

The project is open source in Github On , Address ：https://github.com/springfox/springfox.

Swagger 3.0 What are the changes ？ The official documents summarize the following ：

1. Deleted the springfox-swagger2 The dependence of
2. Delete all @EnableSwagger2... Notes
3. Added springfox-boot-starter Dependencies
4. Removed guava Third party dependence
5. File access address changed , Changed to http://ip:port/project/swagger-ui/index.html.

Let's see here , How do you feel at first ？

Now that someone else has updated it , We can't help it , I 'll introduce you to Spring Boot How to integrate Swagger 3.0 Well .

Spring Boot Version Description

Author use Spring Boot The version is 2.3.5.RELEASE

New dependencies

Swagger 3.0 We already have Spring Boot Integrated starter , Just add the following dependencies ：

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

springfox-boot-starter What has been done ？

Swagger 3.0 One of the main features of the main push is the starter , So what does this starter do ？

「 Remember 」： All classes are automatically configured in the starter logic .

find springfox-boot-starter Automatic configuration class of , stay /META-INF/spring.factories In Archives , as follows ：

As you can see from the picture above , Auto configuration class is OpenApiAutoConfiguration, The original code is 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 {

}

Dare you, this automatic configuration class did nothing , Just import a few configuration classes (@Import) And turn on property configuration (@EnableConfigurationProperties).

「 Emphasis 」： Remember OpenApiDocumentationConfiguration This configuration class , At first glance, this is a BUG, I don't want to go into , The code in it is poorly written , No notes .

Rolling up your sleeves is dry ？

Seriously , It's the same as before , It's really not a big change , Follow the steps of the document step by step .

Customize a basic file example

Everything still needs to be configured manually , Seriously , I thought I would configure it in the global configuration file . Ah , I think too much. . The configuration classes are as follows ：

@EnableOpenApi
@Configuration
@EnableConfigurationProperties(value = {SwaggerProperties.class})
public class SwaggerConfig {
  /**
     *  Configuration properties 
     */
    @Autowired
    private SwaggerProperties properties;

    @Bean
    public Docket frontApi() {
        return new Docket(DocumentationType.OAS_30)
                // Whether to open , Configuration according to environment 
                .enable(properties.getFront().getEnable())
                .groupName(properties.getFront().getGroupName())
                .apiInfo(frontApiInfo())
                .select()
                // Specify the package to scan 
                .apis(RequestHandlerSelectors.basePackage(properties.getFront().getBasePackage()))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     *  Front desk API Information 
     */
    private ApiInfo frontApiInfo() {
        return new ApiInfoBuilder()
                .title(properties.getFront().getTitle())
                .description(properties.getFront().getDescription())
                .version(properties.getFront().getVersion())
                .contact(    // New developer information 
                        new Contact(properties.getFront().getContactName(), properties.getFront().getContactUrl(),
                                properties.getFront().getContactEmail()))
                .build();
    }
}

@EnableOpenApi The annotation file is explained as follows ：

Indicates that Swagger support should be enabled.
This should be applied to a Spring java config and should have an accompanying '@Configuration' annotation.
Loads all required beans defined in @see SpringSwaggerConfig

What do you mean ？ The general meaning is 「 Only the configuration class is marked with @EnableOpenApi This annotation will generate Swagger file 」.

@EnableConfigurationProperties This annotation enables custom property configuration to be enabled , This is the author's custom Swagger To configure .

In short, the configuration is the same as before , According to official documents , You need to add a @EnableOpenApi Notes .

How files are grouped ？

We all know , A project may be divided into Front desk , Backstage ,APP End , Small program side ..... The interface on each end may still be the same , It's impossible to put them all together , It must be distinguished .

therefore , In actual development, files must be grouped .

Grouping is actually very simple ,Swagger towards IOC Put a Docket This is a group file , One of them groupName() Method to specify the name of the group .

So you just need to inject multiple Docket Specify a different group name , Of course , The titles of these documents 、 describe 、 Scanning paths can be customized .

Two are configured as follows Docket, It's divided into front desk and backstage , The configuration classes are as follows ：

@EnableOpenApi
@Configuration
@EnableConfigurationProperties(value = {SwaggerProperties.class})
public class SwaggerConfig {
  /**
     *  Configuration properties 
     */
    @Autowired
    private SwaggerProperties properties;

    @Bean
    public Docket frontApi() {
        return new Docket(DocumentationType.OAS_30)
                // Whether to open , Configuration according to environment 
                .enable(properties.getFront().getEnable())
                .groupName(properties.getFront().getGroupName())
                .apiInfo(frontApiInfo())
                .select()
                // Specify the package to scan 
                .apis(RequestHandlerSelectors.basePackage(properties.getFront().getBasePackage()))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     *  Front desk API Information 
     */
    private ApiInfo frontApiInfo() {
        return new ApiInfoBuilder()
                .title(properties.getFront().getTitle())
                .description(properties.getFront().getDescription())
                .version(properties.getFront().getVersion())
                .contact(    // New developer information 
                        new Contact(properties.getFront().getContactName(), properties.getFront().getContactUrl(),
                                properties.getFront().getContactEmail()))
                .build();
    }
    
    /**
     *  Backstage API
     */
    @Bean
    public Docket backApi() {
        return new Docket(DocumentationType.OAS_30)
                // Whether to open , Configuration according to environment 
                .enable(properties.getBack().getEnable())
                .groupName(" Back office management ")
                .apiInfo(backApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(properties.getBack().getBasePackage()))
                .paths(PathSelectors.any())
                .build();
    }
    
    /**
     *  Backstage API Information 
     */
    private ApiInfo backApiInfo() {
        return new ApiInfoBuilder()
                .title(properties.getBack().getTitle())
                .description(properties.getBack().getDescription())
                .version(properties.getBack().getVersion())
                .contact(    // New developer information 
                        new Contact(properties.getBack().getContactName(), properties.getBack().getContactUrl(),
                                properties.getBack().getContactEmail()))
                .build();
    }
    
}

Attribute configuration file SwaggerProperties as follows , It is divided into two different attribute configurations of foreground and background ：

/**
 * swagger Property configuration class for 
 */
@ConfigurationProperties(prefix = "spring.swagger")
@Data
public class SwaggerProperties {

    /**
     *  Foreground interface configuration 
     */
    private SwaggerEntity front;

    /**
     *  Background interface configuration 
     */
    private SwaggerEntity back;

    @Data
    public static class SwaggerEntity {
        private String groupName;
        private String basePackage;
        private String title;
        private String description;
        private String contactName;
        private String contactEmail;
        private String contactUrl;
        private String version;
        private Boolean enable;
    }
}

Here is a screenshot of the file , You can see that there are two different groups ：

How to add authorization information ？

Project now API There must be license authentication , Otherwise you can't access , For example, ask to carry a TOKEN.

stay Swagger Authentication information can also be configured in , In this way, each request will be carried by default .

stay Docket There are two ways to specify authorization information in , The difference is securitySchemes() and securityContexts(). The configuration in the configuration class is as follows , Building Docket When you set it in, you can ：

    @Bean
    public Docket frontApi() {
        RequestParameter parameter = new RequestParameterBuilder()
                .name("platform")
                .description(" Request head ")
                .in(ParameterType.HEADER)
                .required(true)
                .build();
        List<RequestParameter> parameters = Collections.singletonList(parameter);
        return new Docket(DocumentationType.OAS_30)
                // Whether to open , Configuration according to environment 
                .enable(properties.getFront().getEnable())
                .groupName(properties.getFront().getGroupName())
                .apiInfo(frontApiInfo())
                .select()
                // Specify the package to scan 
                .apis(RequestHandlerSelectors.basePackage(properties.getFront().getBasePackage()))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }

    /**
     *  Set authorization information 
     */
    private List<SecurityScheme> securitySchemes() {
        ApiKey apiKey = new ApiKey("BASE_TOKEN", "token", In.HEADER.toValue());
        return Collections.singletonList(apiKey);
    }

    /**
     *  Global application of authorization information 
     */
    private List<SecurityContext> securityContexts() {
        return Collections.singletonList(
                SecurityContext.builder()
                        .securityReferences(Collections.singletonList(new SecurityReference("BASE_TOKEN", new AuthorizationScope[]{new AuthorizationScope("global", "")})))
                        .build()
        );
    }

After the above configuration is successful , stay Swagger There will be Authorize Button , Just add in the request header . Here's the picture ：

How to carry public request arguments ？

Different architectures may send requests in addition to carrying TOKEN, It also carries different arguments , For example, the requested platform , Version, etc. , The arguments that each request carries are called public arguments .

So how is Swagger How about the public arguments defined in ？ For example, carry in the request header .

stay Docket The method in globalRequestParameters() Public request arguments can be set , The received argument is a List<RequestParameter>, So just build one RequestParameter Assemble , as follows ：

@Bean
public Docket frontApi() {
   // Construct a public request argument platform, Put in header
   RequestParameter parameter = new RequestParameterBuilder()
      // Argument name 
      .name("platform")
      // describe 
      .description(" Requested platform ")
      // Put it in header in 
      .in(ParameterType.HEADER)
      // Is it necessary 
      .required(true)
      .build();
      // Build a set of request arguments 
      List<RequestParameter> parameters = Collections.singletonList(parameter);
        return new Docket(DocumentationType.OAS_30)
                .....
                .build()
                .globalRequestParameters(parameters);
    }

The above configuration is complete , You will see a request header in each interface , Here's the picture ：

It's a rough one BUG

When the author introduces the automatic configuration class, he mentioned , Now let's make a brief analysis of .

OpenApiAutoConfiguration This autoconfiguration class has already imported OpenApiDocumentationConfiguration This configuration class , The following code ：

@Import({
    OpenApiDocumentationConfiguration.class,
    ......
})

@EnableOpenApi The original code of is as follows ：

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

You can see from the original code that ：@EnableOpenApi The function of this annotation is to import OpenApiDocumentationConfiguration This configuration class , Nani ？？？

Now that you're already configuring classes automatically OpenApiAutoConfiguration It's in , Then, whether you need to label the configuration class or not @EnableOpenApi Annotations don't always open Swagger Support ？

「 Test it 」： Do not label on configuration class @EnableOpenApi This note , See if Swagger Perform normally . The results were expected , It can still be executed normally .

「 Summary 」： The author only makes a general analysis of , This could be a BUG Or there are other purposes to follow , So it turns out , I don't want to verify it , It doesn't mean anything .

Summary

This article is also a taste of fresh , I don't feel very fragrant , A little disappointed . Do you like it? ？

Spring Boot The integrated source code has been uploaded , Need friend public name reply key words 「Swagger3.0」 Get . Click to go