Swagger2 most complete explanatory notes

Original link: https://blog.csdn.net/xiaojin21cen/article/details/78654652

Article directories
1, swagger2 annotation Overall Description
2, @Api : request class description
. 3, @ApiOperation : description of the method
　　3.1, @ApiImplicitParams , @ApiImplicitParam : the method described parameters
. 4, @ApiResponses , @ApiResponse : Description method returns a value of
. 5, @ApiModel : JavaBean used above, represents a JavaBean (eg: response data) information
　　5.1, @ApiModelProperty : JavaBean class attribute used in the above described meaning attributes

1, swagger2 comment Overall Description

For the controller class:

annotation	Explanation
@Api	Request class of

The above method for (meaning of the parameters described):

annotation	Explanation
@ApiOperation	Description of the method
@ApiImplicitParams、@ApiImplicitParam	The method of description of the parameters; instructions for specifying individual parameters @ApiImplicitParams

The above method for (or return parameters described object):

annotation	Explanation
ApiResponses @ @ APIResponse	The method described return value; @ApiResponses specifies a single parameter description

Object classes:

annotation	Explanation
@ApiModel	Used in JavaBean class, illustrate the use of JavaBean
@ApiModelProperty	JavaBean class attribute used in the above description of this attribute containing Discussion

2, @ Api: Class Request

@Api: based on the request, in parallel with @Controller, described the role of the class, such as a user module, order the like. 
    Tags = " description of the role of such " 
    value = " The argument does not make sense, so no need to configure "

Example:

@Api (Tags = " line module " ) 
@Controller 
public  class OrderController { 

}

@Api Other property configuration:

Property Name	Remark
value	Url path value
tags	If you set this value, the value of value will be overwritten
description	A description of the resources api
basePath	The basic path

position	If you want to change the order of a plurality of Api the position shown
produces	如, “application/json, application/xml”
consumes	如, “application/json, application/xml”

protocols	Protocol type, such as: http, https, ws, wss.
authorizations	Configuring authentication advanced features
hidden	Configuration is true, hidden in the document

Description of the method: 3, @ ApiOperation

@ApiOperation: " used in the method of the request, the operation of the method " 
    value = " illustrates a method of action " 
    Notes = " Remarks Method "

3.1, @ ApiImplicitParams, @ ApiImplicitParam: Description of method parameters

@ApiImplicitParams: the method used in the request, contains a set of parameters Description 
    @ApiImplicitParam: description of a single parameter         
        name: parameter name 
        value: Character Description parameter explanation 
        required: whether the parameter must pass 
        paramType: parameters on which place 
            · header -> request parameter acquisition: @RequestHeader 
            · Query -> request parameter acquisition: @RequestParam 
            · path (for restful interface) -> Get request parameters: @PathVariable 
            · body (body of the request) ->   @ the User the User requestBody 
            · form (general form submission)        
        dataType: parameter type, default String, other values dataType = " Integer "        
        defaultValue: the default value of the parameter

Column shows:

@Api (= Tags " subscriber module " ) 
@Controller 
public  class the UserController { 

    @ApiOperation (value = " user login " , = Notes " with his mouth Diansha " ) 
    @ApiImplicitParams ({ 
        @ApiImplicitParam (name = " Mobile " , value = " phone number " , required = to true , paramType = " form " ), 
        @ApiImplicitParam (name = " password " , value = "Password ",required=true,paramType="form"),
        @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
    })
    @PostMapping("/login")
    public JsonResult login(@RequestParam String mobile, @RequestParam String password,
    @RequestParam Integer age){
        //...
        return JsonResult.ok(map);
    }
}

4, @ ApiResponses, @ ApiResponse: Method Description return value

@ApiResponses: method returns the object described 
    @ApiResponse: Description of each parameter 
        code: number, for example 400 
        Message: information, e.g. , " request parameter Motian Good " 
        Response: throwing an exception class

Example:

@Api(tags="用户模块")
@Controller
public class UserController {

    @ApiOperation("获取用户信息")
    @ApiImplicitParams({
        @ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value="用户Id")
    }) 
    @ApiResponses({
        @ApiResponse(code = 400, message = "Request parameters Motian good" ), 
        @ApiResponse (code = 404 , Message = " request page no path or wrong path jump " ) 
    }) 
    @ResponseBody 
    @RequestMapping ( " / List " )
     public a JsonResult List (String @RequestParam the userId) { 
        ... 
        return . JsonResult.ok () PUT ( " Page " , pageUtil); 
    } 
}

Information 5, @ ApiModel:: JavaBean used above, represents a JavaBean (such as response data)

@ApiModel: JavaBean classes for the above, this information indicates the entire JavaBean 
            (generally used in such a post created when using such @RequestBody scenario, 
            the request parameter can not be used when describing the annotation @ApiImplicitParam)

5.1, @ ApiModelProperty: JavaBean class attribute used in the above described meaning attributes

Example:

@ApiModel (Description = " return response data " )
 public  class RestMessage the implements the Serializable { 

    @ApiModelProperty (value = " success " )
     Private Boolean = Success to true ; 
    @ApiModelProperty (value = " return object " )
     Private Object Data; 
    @ApiModelProperty ( value = " error number " )
     Private Integer errCode; 
    @ApiModelProperty (value = " error message " )
    private String message;
        
    /* getter/setter 略*/
}