SpringBoot integrates Swagger interface to generate detailed steps for documentation

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


      <!--Swagger use a third party UI-->

2 Create a configuration file to customize the document style

public class Swagger {
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .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

    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")


3 Note in the controller interface

public class VideoController {
    private VideoService videoService;
    @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.

Tags: Java Back-end Spring Boot

Posted by Sirus121 on Wed, 09 Nov 2022 04:38:48 +1030