SwaggerAPI Detailed notes and annotations common parameter configuration

Original Bowen Address: https://blog.csdn.net/java_yes/article/details/79183804

Github official website address: https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X

annotation

@Api：

Acting on the class, the class label for a specific implementation content. This class is a flag indicating swagger of resources.
parameter:

1. tags: Tags can be used () Allows you to set properties for the operation of a plurality of labels, instead of using this property.
2. description: description may describe such effect.

@ApiImplicitParam:

Acting on the method, which represents a separate request parameters
Parameters:

1. name: parameter name.
2. value: the specific meaning of the parameters of the role.
3. required: Required parameter.
4. dataType: the parameter data type.
5. paramType: the type of query parameters, there are several forms:

Types of	effect
path	Submit data in the form of address
query	Automatic mapping is done directly with the parameter assignment
body	Submitted as a stream only supports POST
header	Parameters submitted request headers inside
form	Submitted as a form of support form only POST

Here I was pit once: When I send a POST request was accepted by the entire parameter, whether I use the body or query, the background will be reported Body Missing error. This parameter and @RequestBody conflict SpringMvc in, I simply removed the paramType, and has no effect on the interface testing.

@ApiImplicitParams：

A method comprising a plurality @ApiImplicitParam:
Example:

@ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "book's name", required = true, dataType = "Long", paramType = "query"),
            @ApiImplicitParam(name = "date", value = "book's date", required = false, dataType = "string", paramType = "query")})

@ApiModel:

A class representing the class is described, for receiving the parameter entity class;

@ApiModelProperty：

A method for, field, or data on an explanatory model attribute change operation
Example:

    @ApiModel(value = "User", description = "用户")
    public class User implements Serializable{

    private static final long serialVersionUID = 1546481732633762837L;

    /**
     * 用户ID
     */
    @ApiModelProperty(value = "用户ID", required = true)
    @NotEmpty(message = "{id.empty}", groups = {Default.class,New.class,Update.class})
    protected String id;

    /**
     * code/登录帐号
     */
    @ApiModelProperty(value = "code/登录帐号")
    @NotEmpty(message = "{itcode.empty}", groups = {Default.class,New.class,Update.class})
    protected String itcode;

    /**
     * 用户姓名
     */
    @ApiModelProperty(value = "用户姓名")
    @NotEmpty(message = "{name.empty}", groups = {Default.class,New.class,Update.class})
    protected String name;

@ApiOperation：

A method for indicating the operation of a http request.

    @ApiOperation(value = "获取图书信息", notes = "获取图书信息", response = Book.class, responseContainer = "Item", produces = "application/json")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "book's name", required = true, dataType = "Long", paramType = "query"),
            @ApiImplicitParam(name = "date", value = "book's date", required = false, dataType = "string", paramType = "query")})
    @RequestMapping(value = "/{id}", method = RequestMethod.GET)
    @ResponseBody
    public Book getBook(@PathVariable Long id, String date) {
        return books.get(id);
    }

@ApiResponse:

A method may be described in response to the operation.

@ApiResponses:

A method allowing a plurality of object list ApiResponse wrapper.
example:

@ApiResponses(value = { 
            @ApiResponse(code = 500, message = "2001:因输入数据问题导致的报错"),
            @ApiResponse(code = 500, message = "403:没有权限"),
            @ApiResponse(code = 500, message = "2500:通用报错（包括数据、逻辑、外键关联等，不区分错误类型）")})

@ApiParam:

A method for the parameter, field descriptions, adding metadata to represent the parameters (if required instructions or the like)

@Authorization：

Statement authorization scheme to be used in the resource or operation.

@AuthorizationScope：

OAuth2 introduce a mandate.

@ResponseHeader：

Response header, use.