0 Introduction to Swagger

Swagger is essentially an interface description language for describing RESTful API s represented using JSON. Swagger is used with a set of open source software tools to design, build, document and consume RESTful Web services. Swagger includes automatic documentation, code generation and test case generation.

1 Introduce related dependencies

<!--Swagger2-->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.8.0</version>
</dependency>

      <!--Swagger use a third party UI-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.6</version>
</dependency>
<dependency>
   <groupId>javax.xml.bind</groupId>
   <artifactId>jaxb-api</artifactId>
   <version>2.3.0</version>
</dependency>

2 Create a configuration file to customize the document style

@Configuration
@EnableSwagger2
public class Swagger {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .pathMapping("/")
                .select() // Selecting those paths and api will generate document
                .apis(RequestHandlerSelectors.any())// Monitor all APIs
                //Do not display incorrect interface addresses
                .paths(Predicates.not(regex("/error.*")))//Error paths are not monitored
                .paths(regex("/.*"))// Monitor all paths under the root
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("interface documentation")
                .contact(new Contact("Summer", "http://localhost:8080/doc.html", "903139586@qq.com"))
                .description("Droplet Classroom API interface documentation")
                .termsOfServiceUrl("NO terms of service")
                .license("The Apache License, Version 1.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .version("v1.0")
                .build();
    }

}

3 Note in the controller interface

@RestController
@RequestMapping("/xdclass/")
public class VideoController {
    @Autowired
    private VideoService videoService;
    @RequestMapping("getVideoList")
    @ApiOperation("Get video list method—— getVideoList")
    public Object getVideoList(){
        return videoService.getVideoList();
    }

}

The access address of the interface documentation: http://localhost:8080/doc.html

4 Relevant explanations

@Api: used on the requested class, indicating a description of the class
tags="Annotations that describe the role of this class and can be seen on the UI interface"
value="This parameter is meaningless and can be seen on the UI interface, so no configuration is required"

@ApiOperation: used on the requested method, indicating the purpose and function of the method
value="Describe the purpose and function of the method"
notes="Method notes"

@ApiImplicitParams: used on the requested method, indicating a set of parameter descriptions
@ApiImplicitParam: used in the @ApiImplicitParams annotation to specify various aspects of a request parameter
name: parameter name
value: Chinese character description and explanation of the parameter
required: whether the parameter must be passed
paramType: where to put the parameter
· Header --> Get request parameters: @RequestHeader
· query --> Get request parameters: @RequestParam
· path (for restful interface) –> request parameter acquisition: @PathVariable
div (not commonly used)
form (not commonly used)
dataType: parameter type, default String, other values ​​dataType="Integer"
defaultValue: the default value of the parameter

@ApiResponses: used on the method of the request, representing a set of responses
@ApiResponse: used in @ApiResponses, generally used to express a wrong response information
code: number, such as 400
message: information, such as "request parameters are not filled in"
response: the class that throws the exception

@ApiModel: used on the response class, representing a message that returns response data
(This is generally used when creating a post, using scenarios such as @RequestBody,
When request parameters cannot be described using the @ApiImplicitParam annotation)
@ApiModelProperty: used on properties to describe the properties of the response class

5 Note

When integrating SpringBoot and Swagger, it may fail to integrate with Swagger due to the higher version of SpringBoot.
Solution: Reduce the version of SpringBoot.