Swagger2 annotation (for personal use)

Import dependency

Due to the use of another UI interface, all imported dependencies are one more.

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.10.5</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-spring-webmvc</artifactId>
            <version>2.10.5</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.10.5</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

Configuration class writing

package top.ddandang.swagger.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.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.EnableSwagger2WebMvc;

import java.util.ArrayList;


/**
 * <p>
 * Configure Swagger
 * </p>
 *
 * @author D
 * @version 1.0
 * @date 2020/6/9 16:30
 */

@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {

    /**
     * Configure swagger Docket instance
     * @return Return Docket object
     */
    @Bean
    public Docket docket(Environment environment) {

        // Configure usage environment
        Profiles profiles = Profiles.of("dev");
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(
                // swagger version used
                DocumentationType.SWAGGER_2)
                // Information displayed
                .apiInfo(apiInfo())
                // Used in dev environment
                .enable(flag)
                .select()
                // Specify packages to scan
                .apis(RequestHandlerSelectors.basePackage("top.ddandang.swagger.controller"))
                .build();
    }

    /**
     * Configure swagger apiInfo
     * @return ApiInfo configuration information
     */
    private ApiInfo apiInfo() {

        //Author information
        Contact contact = new Contact("D", "www.ddandang.top", "875708765@qq.com");

        return new ApiInfo(
                // title
                "test Swagger2 API",
                // describe
                "D",
                // Version number
                "1.0",
                // Terms of service website
                "urn:tos",
                // Author information
                contact,
                // permit
                "Apache 2.0",
                // License website
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

Access page

swagger comes with UI

http://localhost:7070/swagger-ui.html

Third party UI

http://localhost:7070/doc.html

Common notes

@Api

Common properties

attribute	type	effect
@Api	Scope of action	class
value	String	Used to describe the role of the class (not displayed in the UI interface)
tags	String[]	Group this class (all interfaces inside)

value
Used to describe the role of the class (not displayed in the UI interface)

@RestController
@RequestMapping("/admin")
@Api(value = "Admin controller")
public class AdminController {

    @GetMapping("/login")
    public R login() {
        return R.failed();
    }

    @GetMapping("/register")
    public R register() {
        return R.failed();
    }
}

tags
If the tags of two classes are the same, all interfaces under the two classes will be displayed under one tag.

@RestController
@RequestMapping("/admin")
@Api(value = "Admin controller", tags = {"User operation", "Administrator action"})
public class AdminController {

    @GetMapping("/login")
    public R login() {
        return R.failed();
    }

    @GetMapping("/register")
    public R register() {
        return R.failed();
    }
}


@RestController
@Api(value = "User operated interface", tags = {"User operation"})
@RequestMapping("/user")
public class UserController {

    @GetMapping("/login")
    public R login() {
        return R.success();
    }
}

@ApiIgnore

Ignore the display of the whole class in the UI interface, or a method or a parameter of a method.

Common properties

attribute	type	effect
@ApiIgnore	Scope of action	Parameters of class, method and interface
value	String	A short explanation of why this parameter / action is ignored

@RestController
@RequestMapping("/admin")
@Api(value = "Admin controller", tags = {"User operation", "Administrator action"})
public class AdminController {

    @ApiIgnore
    @GetMapping("/login")
    public R login() {
        return R.failed();
    }

    @GetMapping("/register")
    public R register(@ApiIgnore(value = "Useless parameters") String username, String password) {
        return R.failed();
    }
}

@ApiIgnore(value = "Classes that do not need to be displayed")
@RestController
@Api(value = "User operated interface", tags = {"User operation"})
@RequestMapping("/user")
public class UserController {

    @GetMapping("/login")
    public R login() {
        return R.success();
    }
}

@ApiOperation

Explain the function and purpose of the method and act on the method

Common properties

attribute	type	effect
@ApiOperation	Scope of action	Method, class (not commonly used)
value	String	Brief description of this operation
notes	String	A detailed description of the operation
tags	String[]	Consistent with the tags parameter of @ Api annotation, the interface is logically classified

@RestController
@Api(value = "User operated interface", tags = {"User operation"})
@RequestMapping("/user")
public class UserController {

    @ApiOperation(value = "User login interface", notes = "The user logs in with the account and password", tags = {"Sign in"})
    @PostMapping("/login")
    public R login(String username, String password) {
        return R.success();
    }

    @ApiOperation(value = "User registration interface", notes = "The user logs in with the account and password", tags = {"register"})
    @PostMapping("/register")
    public void register(String username, String password) {

    }
}

@RestController
@RequestMapping("/admin")
@Api(value = "Admin controller", tags = {"User operation", "Administrator action"})
public class AdminController {


    @ApiOperation(value = "Administrator login interface", notes = "The user logs in with his mobile number and password", tags = {"Sign in"})
    @PostMapping("/login")
    public R login(String phone, String password) {
        return R.failed();
    }

    @PostMapping("/register")
    public R register(@ApiIgnore(value = "Useless parameters") String username, String password) {
        return R.failed();
    }
}

value and notes attributes

@ApiImplicitParams

It needs to be used together with @ ApiImplicitParam to describe various parameters of the interface

attribute	type	effect
@ApiImplicitParams	Scope of action	Method, used in conjunction with @ ApiImplicitParam
value	ApiImplicitParam[]

@ApiImplicitParam

Common properties

attribute	type	effect
@ApiImplicitParam	Scope of action	method
name	String	Parameter name
value	String	Brief description of parameters
defaultValue	String	Describes the default value of the parameter
required	boolean	Is the parameter required
dataType	String	When the data type of the parameter (String, Integer, etc.) is Integer, the transmission fails. It is recommended to encapsulate the entity class to pass more than 2 parameters
paramType	String	Parameter request methods (query, path) are not commonly used: body, header, form
		query: corresponding to @ RequestParam? transmit
		Path: the corresponding @ pathvariable {} path is passed

@RestController
@Api(value = "user operation interface", tags = {"user operation"})
@RequestMapping("/user")
public class UserController {

@ApiOperation(value = "User login interface", notes = "The user logs in with the account and password", tags = {"Sign in"})
@PostMapping("/login")
public R login(String username, String password) {
    return R.success();
}

@ApiOperation(value = "User registration interface", notes = "Users register with account, password and age", tags = {"register"})
@ApiImplicitParams({
        @ApiImplicitParam(name = "username", value = "account number", required = true, dataType = "String", paramType = "query"),
        @ApiImplicitParam(name = "password", value = "password", defaultValue = "123456", required = true, dataType = "String", paramType = "query")
})
@PostMapping("/register")
public R register(String username, String password) {

    Map<String, Object> map = new HashMap<>();
    map.put("username", username);
    map.put("password", password);
    return R.success().data(map);
}

}

@ApiResponses

It needs to be used with @ ApiResponse to describe the possible response of interface method or class operation.

attribute	type	effect
@ApiResponses	Scope of action	Methods and classes, used in conjunction with @ ApiResponse
value	ApiResponse[]

@ApiResponse

Common properties

attribute	type	effect
@ApiResponse	Scope of action	@ApiResponses internal
code	int	HTTP status code of the response
message	String	Response information (description)

@ApiOperation(value = "Administrator registration interface", notes = "The administrator uses the account and password to register", tags = {"register"})
@ApiImplicitParams({
        @ApiImplicitParam(name = "username", value = "account number", required = true, dataType = "String", paramType = "query"),
        @ApiImplicitParam(name = "password", value = "password", defaultValue = "123456", required = true, dataType = "String", paramType = "query"),
        @ApiImplicitParam(name = "confirmPassword", value = "Confirm password", defaultValue = "123456", required = true, dataType = "String", paramType = "query")
})
@ApiResponses(value = {
        @ApiResponse(code = 2000, message = "Request succeeded"),
        @ApiResponse(code = 4000, message = "Request error"),
        @ApiResponse(code = 4001, message = "The two passwords are inconsistent")
})
@PostMapping("/register")
public R register(@ApiIgnore(value = "Useless parameters") String username, String password, String confirmPassword) {

    Map<String, Object> map = new HashMap<>();
    map.put("username", username);
    map.put("password", password);
    map.put("confirmPassword", password);
    if (!password.equals(confirmPassword)) {
        return R.failed().code(4001).message("The two passwords are inconsistent");
    }
    return R.success().data(map);
}

@ApiModel

Indicates a description of the class, which is used to receive parameters with entity classes

attribute	type	effect
@ApiModel	Scope of action	class
value	String	Is the alias of the class. By default, the class name is used
description	String	Provides a detailed description of the class.

@ApiModel(value = "newAdmin", description = "The user accepts the entity class encapsulated by the parameters registered by the user")
@Data
@Accessors(chain = true)
@AllArgsConstructor
@NoArgsConstructor
public class Admin implements Serializable {
    private String name;
    private String username;
    private String password;
}

@RestController
@RequestMapping("/admin")
@Api(value = "Admin controller", tags = {"User operation", "Administrator action"})
public class AdminController {
    @ApiOperation(value = "Administrator registration interface", notes = "The administrator uses the account and password to register(Accept using entity classes)", tags = {"register"})
    @ApiResponses(value = {
            @ApiResponse(code = 2000, message = "Request succeeded"),
            @ApiResponse(code = 4000, message = "Request error"),
            @ApiResponse(code = 4001, message = "The two passwords are inconsistent")
    })
    @PostMapping("/newRegister")
    public R newRegister(@RequestBody Admin admin) {
        return R.success().data("admin", admin);
    }
}

@ApiModelProperty

Describe the model attribute

attribute	type	effect
@ApiModelProperty	Scope of action	Fields (common), methods
value	String	A short description of this property
name	String	Override the name of the property (not used...)
required	boolean	The specified parameter is required or not.
hidden	boolean	Hide change attribute

@ApiModel(description = "The user accepts the entity class encapsulated by the parameters registered by the user")
@Data
@Accessors(chain = true)
@AllArgsConstructor
@NoArgsConstructor
public class Admin implements Serializable {

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

    @ApiModelProperty(value = "account number", required = true, hidden = true)
    private String username;

    @ApiModelProperty(value = "password", required = true)
    private String password;
}