1 Swagger

1.1 Introduction to Swagger

The OpenAPI Specification (OAS) is a project of the Linux Foundation that attempts to standardize RESTful service development by defining a language that describes the API format or API definition. The current version is V3.0 and is published and open source on github.
(https://github.com/OAI/OpenAPI-Specification)
Swagger is the largest OpenAPI specification (OAS) API development tool framework in the world, supporting the development of the entire API lifecycle from design and documentation to testing and deployment.( https://swagger.io/)
Spring Boot integrates Swagger and generates the Swagger interface. Spring Boot is the magic weapon in Java and is the framework for building projects quickly under the Spring project.

1.2 Swagger Common Notes

Add Swagger's comment to the Java class to generate the Swagger interface. Common Swagger notes are as follows:

@Api: Decorates the entire class to describe the Controller's role
@ApiOperation: Describes a method of a class, or an interface
@ApiParam: Single parameter description
@ApiModel: Receive parameters with objects
@ApiModelProperty: A field describing an object when it receives parameters
@ApiResponse:One of the HTTP responses describes @ApiResponses:Overall description of the HTTP response @ApiIgnore: Ignore this API with this comment
@ApiError: Information returned when an error occurred
@ApiImplicitParam: a request parameter
@ApiImplicitParams: Multiple request parameters

@ApiImplicitParam property:

1.3 Swagger interface definition

Modify the page query interface in the interface project and add Swagger annotations.For example: Paging query interface test

@Api(value="Page management interface",description = "Page management interface to add, delete, change, check pages")
public interface CmsPageControllerApi {
@ApiOperation("Paging Query Page List")
@ApiImplicitParams({
@ApiImplicitParam(name="page",value = "Page Number",required=true,paramType="path",dataType="int"),
@ApiImplicitParam(name="size",value = "Number of records per page",required=true,paramType="path",dataType="int")
})
public QueryResponseResult findList(int page, int size, QueryPageRequest queryPageRequest) ;
}

Use the annotation ApiModelProperty in the QueryPageRequest class to annotate attributes:

@Data
public class QueryPageRequest extends RequestData {
//Site id
@ApiModelProperty("site id")
private String siteId;
//Page ID
@ApiModelProperty("page ID")
private String pageId;
//page name
@ApiModelProperty("page name")
private String pageName;
//Page Alias
@ApiModelProperty("Page Alias")
private String pageAliase;
//Template id
@ApiModelProperty("Template id")
private String templateId;
}

1.4 Swagger interface test

How Swagger interface generation works:
1. System Startup, Scan to Wagger2Configuration Class in api Project
2. Specify the package path in this class and find the controller class labeled @RestController annotation under this package and subpackages
3. Generate interface documents based on Swagger annotations in the controller class.
Start the cms service project, view the interface documentation, request: http://localhost:31001/swagger-ui.html

*.Swagger2Configuration class

@Configuration
@EnableSwagger2
public class Swagger2Configuration {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("<package path>"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("api File")
                .description("api File")
//                .termsOfServiceUrl("/")
                .version("1.0")
                .build();
    }
}

• Note: Postman software is also recommended to achieve the same function.