当前位置:网站首页>Swagger2 document editing

Swagger2 document editing

2020-12-18 16:13:52 Z Hai Rui Z

Key notes

maven rely on

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.9.2</version>
</dependency>

<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>swagger-bootstrap-ui</artifactId>
	<version>1.9.6</version>
</dependency>

Note key overall description

Act on controller Class :

Note key explain
@Api Description of the request class

@Api : Request class description

@Api: Put it on the requested class , And  @Controller  Juxtaposition , Explain the role of classes , Such as user module , Orders, etc .
   Parameter description :
	tags=" Explain the role of this class "
	value=" This parameter doesn't make sense , So there's no need to configure "

Example :

@RestController
@RequestMapping("/user")
@Api(tags=" User registration related interface ")
@AllArgsConstructor
public class UserRegisterController {
   
    // controller Layer code 
}

@Api Other attribute configuration

The attribute name remarks
value url The road strength of
tags Set the value ,value The value of will be overridden
description Yes api Description of resources
basePath The basic path
position Configure multiple Api Want to change the order of the display position
produces Such as , “application/json, application/xml”
consumes Such as , “application/json, application/xml”
protocols Protocol type , Such as : http, https, ws, wss
authorizations Configure for advanced feature authentication
hidden Configure to true , Will be hidden in the document

Act on a class ( Object class ):

Note key explain
@ApiModel Use in JavaBean Class , explain JavaBean Of purpose
@ApiModelProperty Use in JavaBean Class properties , Indicates the implication of this property

@ApiModel: Act on JavaBean, Said to JavaBean Description of the function of

  • When data description is requested ( namely @RequestBody when ), Used to encapsulate requests ( It includes all kinds of verification of data ) data
  • When the response value is an object ( namely @responseBody when ), A description of the return value object

@ApiModelProperty: Act on JavaBean Class properties , Explain the meaning of the attribute

Entity class

@Data
@ApiModel(value= " Send captcha parameters ")
public class CheckRegisterSmsParam {
   

	@ApiModelProperty(value = " cell-phone number ")
	@Pattern(regexp= PrincipalUtil.MOBILE_REGEXP,message = " Please input the correct mobile number ")
	private String mobile;

	@ApiModelProperty(value = " Verification Code ")
	private String validCode;
}

controller layer

@RestController
@RequestMapping("/user")
@Api(tags=" User registration related interface ")
@AllArgsConstructor
public class UserRegisterController {
   
    @PutMapping("/checkRegisterSms")
    @ApiOperation(value=" Verification code ", notes=" The verification code returns the identification of successful verification ")
    public ResponseEntity<String> register(@Valid @RequestBody CheckRegisterSmsParam checkRegisterSmsParam) {
   
        //  Every ip Only 10 registered verification codes can be sent per minute , To avoid the interface being used 
        if (!smsLogService.checkValidCode(checkRegisterSmsParam.getMobile(), checkRegisterSmsParam.getValidCode(), SmsType.REGISTER)){
   
            throw new YamiShopBindException(" The verification code is wrong or expired ");
        }
        String checkRegisterSmsFlag = IdUtil.simpleUUID();
        RedisUtil.set(CHECK_REGISTER_SMS_FLAG + checkRegisterSmsFlag, checkRegisterSmsParam.getMobile(), 600);
        return ResponseEntity.ok(checkRegisterSmsFlag);
    }
}

 Insert picture description here

Act on the method ( Description of request parameters ):

Note key explain
@ApiOperation Method description
@ApiImplicitParams、@ApiImplicitParam A description of the parameters of the method ;@ApiImplicitParams A description for specifying a single parameter

@ApiOperation: Act on the method , Explain the method

@ApiOperation" Used in the method of request , Explain the function of the method "
	value=" Explain the function of the method "
	notes=" Method notes "

 Insert picture description here

@ApiImplicitParams@ApiImplicitParam: Act on the method , Description of method parameters

@ApiImplicitParams: Used in the method of request , Contains a set of parameter descriptions 
	@ApiImplicitParam: A description of a single parameter 	    
	    name: Parameter name 
	    value: Parameter description 、 describe 
	    required: Whether the parameter must be required 
	    paramType: Where are the parameters placed 
	        · query -->  Get request parameters :@RequestParam
	        · header -->  Get request parameters :@RequestHeader	      
	        · path( be used for restful Interface )-->  Get request parameters :@PathVariable
	        · body( Request body )-->  @RequestBody User user
	        · form( Normal form submission )	   
	    dataType: Parameter type , Default String, Other values dataType="Integer"	   
	    defaultValue: The default value of the parameter 

Example :

@Api(tags=" User module ")
@Controller
public class UserController {
   
	@ApiOperation(value=" The user login ",notes=" Just say something ")
	@ApiImplicitParams({
   
		@ApiImplicitParam(name="mobile",value=" cell-phone number ",required=true,paramType="form"),
		@ApiImplicitParam(name="password",value=" password ",required=true,paramType="form"),
		@ApiImplicitParam(name="age",value=" Age ",required=true,paramType="form",dataType="Integer")
	})
	@PostMapping("/login")
	public JsonResult login(@RequestParam String mobile, @RequestParam String password,
	@RequestParam Integer age){
   
		//...
	    return JsonResult.ok(map);
	}
}

Act on the method ( Return the description of the parameter ):

Note key explain
@ApiResponses、@ApiResponse Description of the return value of the method ;@ApiResponses A description for specifying a single parameter

@ApiResponses@ApiResponse: Act on the method , State code description of the return value of the method

@ApiResponses: Method returns the description of the object 
	@ApiResponse: Description of each parameter 
	    code: Numbers , for example 400
	    message: Information , for example " The request parameter is not filled in "
	    response: The class that threw the exception 

Example :

@Api(tags=" User module ")
@Controller
public class UserController {
   

	@ApiOperation(" Get user information ")
	@ApiImplicitParams({
   
		@ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value=" user Id")
	}) 
	@ApiResponses({
   
		@ApiResponse(code = 200, message = " The request is successful "),
		@ApiResponse(code = 400, message = " The request parameter is not filled in "),
		@ApiResponse(code = 404, message = " The request path does not exist or the page Jump path is wrong ")
	}) 
	@ResponseBody
	@RequestMapping("/list")
	public JsonResult list(@RequestParam String userId) {
   
		...
		return JsonResult.ok().put("page", pageUtil);
	}
}

版权声明
本文为[Z Hai Rui Z]所创,转载请带上原文链接,感谢
https://chowdera.com/2020/12/20201218161318176a.html

随机推荐