Swagger study notes

Swagger

After the front and rear ends are separated , The front and rear end integrated joint commissioning will result in the failure of timely negotiation , Solve interface interaction problems in time .

The front end often complains that the interface document given by the back end is inconsistent with the actual situation . The back end also thinks that writing and maintaining interface documents will cost a lot of energy , Often too late to update .

Over time , Version of the iteration , Interface documents can easily fail to keep up with the code .

As a programmer , Two things I hate most ：1、 Others don't write notes .2、 Write your own notes .

1、 What is? Swagger?

Swagger Is a normative and complete framework , Used to generate 、 describe 、 Invocation and visualization RESTful Style Web service .

Swagger The goal is to RESTful API Define a standard, language independent interface , People and computers can access the source code without 、 Document or discover and understand the functions of the service through network traffic monitoring .

Swagger After correct definition , The user can understand the remote service and interact with the remote service with minimal implementation logic .

Swagger Support API Automatic generation of synchronized online documents also supports online testing .

Swagger Official website

Similar to that : Lkadoc Interface documentation tools

2、SpringBoot Integrate Swagger

1. Create a new one SpringBootWeb project .

2. Import correlation dependency

   3.0 Dependencies imported from previous versions

   <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>3.0.0</version>
   </dependency>
   <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <version>3.0.0</version>
   </dependency>
   

   3.0 After version Swagger Use the starter

   <!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-boot-starter</artifactId>
       <version>3.0.0</version>
   </dependency>
   

3. To write Helloworld

4. To configure Swagger （Config）

   @Configuration
   // @EnableSwagger2 //  Turn on  Swagger2 3.0 Previous version 
   @EnableOpenApi         // 3.0  edition 
   public class SwaggerConfig {
         
   }
   

5. test run

   Access address ：http://localhost:8080/swagger-ui/index.html You can see it swagger Backend interface .

3、 To configure Swagger Information

4、 Configure scanning interface and document

@Configuration
// @EnableSwagger2 //  Turn on  Swagger2 3.0 Previous version 
@EnableOpenApi      // 3.0  edition 
public class SwaggerConfig {
    

    //  Configured with  swagger  Of  Docket  Of  bean  example 
    @Bean
    public Docket docket(){
    
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
            	//  Configure whether to enable  swagger
            	.enable(true)
                .select()
                // RequestHandlerSelectors： Configure the interface mode to be scanned 
                // basePackage()  Specify packages to scan 
                // any()  Scan all 
                // none()  No scanning 
                // withClassAnnotation()  Scan annotations on classes , The parameter is the return object of an annotation 
                // withMethodAnnotation()  Notes on scanning methods 
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
                // paths():  Filter path 
                .paths(PathSelectors.ant("/example/**"))
                .build();
    }

    //  To configure  Swagger  Information  apiInfo
    private ApiInfo apiInfo(){
    
        //  The author information 
        Contact contact = new Contact(" bread ", "http://localhost", "[email protected]");
        return new ApiInfo(
                " bread  API  file ",
                " This is a description of ",
                "1.0",
                "http://localhost",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>()
        );
    }
}

Swagger Use in a specific environment ：

• Judge the environment used （application-dev.properties、application-pro.properties、application-test.properties）

• Inject enable( false )

  # application.properties
  spring.profiles.active=dev
  

  //  You can make the annotation fetch environment 
  @Value("${spring.profiles.active}")
  private String env;
  -----------------------------------------------------------------
      
  //  Set what to display  Swagger  Environmental Science 
  Profiles profiles = Profiles.of("dev", "test");
  //  Get the environment of the project 
  boolean flag = environment.acceptsProfiles(profiles);
  
  

5、 To configure API Grouping documents

.groupName(" bread ")

One Docket Corresponding to a group ：

@Bean
public Docket docket1(){
    
    return new Docket(DocumentationType.SWAGGER_2).groupName(" grouping 1");
}

@Bean
public Docket docket2(){
    
    return new Docket(DocumentationType.SWAGGER_2).groupName(" grouping 2");
}

@Bean
public Docket docket3(){
    
    return new Docket(DocumentationType.SWAGGER_2).groupName(" grouping 3");
}

Entity class configuration ：

1、 As long as the return value of our interface , There are returns of entity classes , He'll be scanned to swagger in

2、 Used on user entity classes @ApiModel("xx Entity class ") Use annotations on attributes @ApiModelProperty("xxx")

【 Be careful 】： It should be closed when it is officially released swagger ！！ Safe on , It also saves memory consumption ！！