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