2024.5.31 Friday
Following up on【WEEK14】 【DAY4】Swagger Part 2【English Version】

16.6. Configure API Groups

16.6.1. Modify SwaggerConfig.java

package com.P47.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration  // Equivalent to @Component
@EnableSwagger2 // Enable Swagger2
public class SwaggerConfig {
    // Configure the bean instance Docket for Swagger, to set specific parameters for Swagger
    @Bean
    public Docket docket(Environment environment){

        // Set the environments where Swagger should be displayed
        Profiles profiles = Profiles.of("dev", "test");
        // Determine if the current environment matches the profiles
        // Use enable() to accept this parameter and decide whether to display
        boolean flag = environment.acceptsProfiles(profiles);
        flag=true;  // To access through port 8080, and because the dev and test profile ports do not include 8080, manually set flag to true to ensure enable(flag) starts normally.

        return new Docket(DocumentationType.SWAGGER_2)  // See the source code in DocumentationType.classpublic class DocumentationType extends SimplePluginMetadata method, select the appropriate version for editing
                .apiInfo(apiInfo()) // Public Docket(DocumentationType documentationType) method, click on ApiInfo to go to ApiInfo.class
                .enable(flag)  // Whether to enable Swagger, if false it cannot be started, and the page shows: 😱 Could not render e, see the console.
                .groupName("ZzzZzzzZzzzz-") // Rename the default group to a custom name

                .select()   // Configure the scanning interface using the .select() method, RequestHandlerSelectors configures how to scan interfaces
                //.apis(RequestHandlerSelectors.basePackage("com.P47.controll"))  // Use basePackage to specify the package to scan
                //.paths(PathSelectors.ant("/P47/**"))    // Click on path to see the initialization of private Predicate<String> pathSelector; Here, using the .ant() method as an example, only scan interfaces with requests starting with /P47
                .build();

    }
    // Configure multiple groups, when accessing these groups in the page, the page is set to the default settings: because no other configuration is done
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
    }

    // Configure Swagger information (apiInfo)
    ......
}

16.6.2. Restart

Select group1, group2, and group3 respectively

16.7. Entity Configuration

16.7.1. Create a new pojo folder

Create User.java

@ApiModel adds annotations to the class
@ApiModelProperty adds annotations to the class properties

package com.P47.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("User Entity")
public class User {
    @ApiModelProperty("Username")
    public String username;
    @ApiModelProperty("Password")
    public String password;
}

16.7.2. Modify HelloController.java

package com.P47.controller;

import com.P47.pojo.User;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @RequestMapping(value = "/hello")
    public String hello(){
        return "hello";
    }

    @RequestMapping("/getUser")
    public User getUser(){
        return new User();  // The User.java just created is the return value of the getUser request interface, so it can be mapped to the entity item (which can be displayed in the Models section on the page)
    }
}

As long as this entity is in the return value of the request interface (even if it is a generic type), it can be mapped to the entity item.
Note: It is not because of the @ApiModel annotation that the entity is displayed here, but because any entity that appears in the return value of the interface method will be displayed here. The @ApiModel and @ApiModelProperty annotations are only used to add comments to the entity.

16.7.3. Restart

16.8. Common Annotations

16.8.1. All Swagger annotations are defined in the io.swagger.annotations package

Here are some commonly used ones. Those not listed can be referred to in the documentation:

Swagger Annotation	Brief Description
@Api(tags = “xxx module description”)	Used on module classes
@ApiOperation(“xxx interface description”)	Used on interface methods
@ApiModel(“xxx POJO description”)	Used on model classes: such as VO, BO
@ApiModelProperty(value = “xxx property description”, hidden = true)	Used on class methods and properties, hidden can hide the property
@ApiParam(“xxx parameter description”)	Used on parameters, methods, and fields, similar to @ApiModelProperty

16.8.2. We can also configure some annotations for the request interfaces (modify HelloController.java)

package com.P47.controller;

import com.P47.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

@Api(tags = "Text explanation for HelloController")
@RestController
public class HelloController {

    @GetMapping(value = "/hello")   // Changed from RequestMapping
    public String hello(){
        return "hello";
    }

    @PostMapping("/getUser")    // Changed from RequestMapping
    public User getUser(){
        return new User();  // The User.java just created is the return value of the getUser request interface, so it can be mapped to the entity item (which can be displayed in the Models section on the page)
    }

    @ApiOperation("Annotation of the interface")
    @PostMapping("/trytry")
    @ResponseBody
    public String Zzz(@ApiParam("The returned name annotation is written here") String usernameaa){
        return usernameaa;
    }
}

16.8.3. Restart

You can click “try it out” in the upper right corner to test.
For example:


Advantages: It can add some configuration information to attributes or interfaces that are difficult to understand, making them easier to read!
Compared with the traditional way of testing interfaces with Postman or Curl, using swagger is simply foolproof. It does not require additional documentation (well-written documentation itself) and is less prone to errors. You only need to enter the data and click Execute. If combined with an automated framework, it can be said that no manual operation is needed at all.
Swagger is an excellent tool, and many small and medium-sized internet companies in China are already using it. Compared with the traditional way of writing a Word interface document first and then testing, this approach is more in line with the current rapid iterative development trend. Of course, remember to turn off Swagger in the production environment for security reasons and to save runtime memory.