Introduction to swagger

Official introduction

THE WORLD'S MOST POPULAR API TOOLING
Swagger is the world's largest framework of API developer tools for the OpenAPI Specification(OAS),
enabling development across the entire API lifecycle, from design and documentation, to test and deployment.

First of all, Swagger is the most popular API tool in the world, and its purpose is to support the development of the entire API life cycle, including design, documentation, testing and deployment. Using swagger can save the time of writing interface documents, and it is also convenient to test the interface. Here's how to integrate swagger in spring boot.

Introducing dependencies

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

To configure

New Swagger2Config.class

/**
 * @author Happy
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createAdminApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("api")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.happyjava.springboot"))
                .paths(PathSelectors.any())
                .build();
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("system interface")
                .description("Test System Interface")
                .version("1.0")
                .build();
    }
}

The basic information of swagger is configured here, which can be customized according to specific needs.

Effect

After completing the above two steps, we can see the effect of swagger. open http://127.0.0.1:8080/swagger-ui.html The results are as follows:

These are some of the interfaces I wrote before.

Using swagger debugging interface

There are three classes, ResultVO.class, SwaggerTestController.class and TestParam.class, as follows:

@Data
public class ResultVO {

    private String result;

    private String message;

}

@RestController
@RequestMapping(value = "/api/swagger")
public class SwaggerTestController {

    @PostMapping
    public ResultVO test(TestParam param) {
        return new ResultVO();
    }

}

@Data
public class TestParam {

    private String username;

}

Restart the application to see the effect:

As you can see, the request and response parameters of the interface are automatically listed in the swagger document.

Click Try it out and the input box pops up. We can enter the test parameters here as follows:

After the parameters are input, click Execute:

The results of the response can be obtained here.

Field description

Although swagger has automatically helped us build the interface document here, the lack of field descriptions will make front-end and back-end collaboration less comfortable. Swagger can add descriptive attributes to fields in the form of annotations.

Entity parameter description

When interface parameters are in the form of @RequestBody, ApiModel can be used to identify classes and ApiModel Property to identify properties. Modify TestParam.class as follows:

@Data
@ApiModel(value = "Test parameters")
public class TestParam {

    @ApiModelProperty(value = "User name", required = true)
    private String username;

}

Restart the application to see the effect:

Click Model to see the description of the field.

Field parameter description

If we accept parameters in the form of queryString, or get requests, then the @ApiParam annotation describes fields. Modify SwaggerTest Controller by adding the following methods:

    @GetMapping
    public ResultVO get(@ApiParam(value = "request id") String requestId) {
        return new ResultVO();
    }

Restart application view effect:

Response parameter description

We also need to describe the field of the response, which is consistent with the usage in the entity parameter description. Modify ResultVO.class as follows:

@Data
@ApiModel(value = "response")
public class ResultVO {

    @ApiModelProperty(value = "This is the result.")
    private String result;

    @ApiModelProperty(value = "This is information.")
    private String message;

}

Restart application view effect:

summary

springboot inherits swagger and uses swagger's annotations to describe fields of parameters and responses. Swagger also has rich usage when describing fields. specific api readers can view api documents when they need them.