Swagger2 interface document basic usage method

Swagger2

1. Introduction

The Swagger interface document is a commonly used tool for front-end and back-end separation. From the interface document, you can directly send a request to test the interface, which has the following advantages:

1. Api documentation and API definition are updated synchronously

2. Run directly, you can test the API interface online

3. Support multiple languages

Official website: https://swagger.io/

Two, Swagger2 configuration

2.1 Dependencies that need to be introduced

</dependency>
<!--swagger2 依赖-->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.7.0</version>
</dependency>
<!-- swagger2 ui依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

Of course, third-party UI interfaces written by other authors can also be introduced

<!--Swagger第三方UI依赖-->
<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>swagger-bootstrap-ui</artifactId>
  <version>1.9.6</version>
</dependency>

2.2 Configuration class annotations

@Configuration
@EnableSwagger2
public class Swagger2Config {
    
    
  
}

2.3 Configure Docket instance

@Bean
public Docket  createRestApi(){
    
    
    return new Docket(DocumentationType.SWAGGER_2);
}

2.4 Configure swagger apiInfo

private ApiInfo apiInfo(){
    
    
    return new ApiInfoBuilder()
            .title("云E办接口文档")
      			.description("接口文档")
            .contact(new Contact("sdh",
                                 "https://xxxxxxx.github.io/",
                                 "[email protected]"))
            .version("1.0")
            .build();
}

where title is the document name

description is the document description

contact is author information

version is the version

2.5 Swagger configuration scanning interface

@Bean
public Docket  createRestApi(){
    
    
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
          	.apis(RequestHandlerSelectors.
         		 			basePackage("com.xxx.server.controller"))
            .paths(PathSelectors.any())
            .build();
}

Among them, apiInfo() is passed in the apiInfo we just wrote, and then .select starts to configure the scanning interface. Here, the builder mode is adopted. After .selcet, there are only three options: .apis, .paths, and .build.

(1) .apis

.apis(RequestHandlerSelectors.basePackage())

basePackage() means based on package scanning, such as the following example

.apis(RequestHandlerSelectors.basePackage("com.sundaohan.server.controller"))

any() means search all

.apis(RequestHandlerSelectors.any())

none() means not to scan

.apis(RequestHandlerSelectors.none())

withClassAnnatation() indicates scanning by annotation on the class, and needs to pass in an annotation reflection object

.apis(RequestHandlerSelectors.withMethodAnnotation())

For example, if you want to scan classes modified by RestController annotations

.apis(RequestHandlerSelectors.withMethodAnnotation(RestController.class))

withMethodAnnotation() means to scan according to the annotation on the method, you need to pass in a reflection object of the annotation

.apis(RequestHandlerSelectors.withMethodAnnotation())

For example, if you want to scan the method modified by GetMapping

.apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))

(2) .paths

.paths() is used to filter paths, indicating what path to scan for content

.any() means to scan the contents of all paths

.paths(PathSelectors.any())

.none() means not scanning at all

.paths(PathSelectors.none())

.ant() means to scan the interface with the specified path, such as

.paths(PathSelectors.ant("/api/**"))

Indicates that only interfaces whose requests start with /api are scanned, and others will not be scanned

(3).enable()

To control whether swagger is enabled, a boolean value needs to be passed in as a parameter, and the default is true, which means it is enabled

If you want to close, just pass in false

.enable(false)

After the setting is complete, visit localhost:port number/doc.html to see the interface document interface