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;
}


Other instructions

Personal swagger MD file
HTTP status code definition

The interface information can be directly exported to markdown

Tags: Java RESTful

Posted by cs1h on Sat, 21 May 2022 13:18:51 +0300