This note is constantly updated with some content from the Internet, the main CSDN blog (see Resources) @[TOC]

Swagger part

scope API Use location
Object properties @ApiModelProperty Used on fields of the inbound and outbound parameter objects
Protocol Set Description @Api For the Controller class
Protocol description @ApiOperation Let’s use the controller method
The Response set @ApiResponses Let’s use the controller method
Response @ApiResponse Used in @ApiResponses
A non-object parameter set @ApiImplicitParams Let’s use the controller method
Non-object parameter description @ApiImplicitParam In the @apiImplicitParams method
Describes the meaning of the returned object @ApiModel Used on return object classes

classification

For the Controller class:

annotations instructions
@Api A description of the request class

For methods (specifying the meaning of the parameters) :

annotations instructions
@ApiOperation Method description
@ ApiImplicitParams, @ ApiImplicitParam Description of method parameters; @apiIMPLICITParams Is used to specify the description of a single parameter

Used above a method (to return a description of an argument or object) :

annotations instructions
@ ApiResponses, @ ApiResponse A description of the return value of a method; @apiresponses Used to specify the description of a single parameter

Object classes:

annotations instructions
@ApiModel Used on a JavaBean class to describe the purpose of a JavaBean
@ApiModelProperty Used on a JavaBean class property to indicate the properties of the property

@Api

  • Identifies this class asswaggerThe resources of
  • Used forclassMainly onrequestThe class)
    • with@Controlleror@RestControllerTied for
  • instructionsFunctions of this classSuch as user module order class and so on
@api (value = "description (this parameter is meaningless, so no need to configure) ", tags = {" tags "})
Copy the code
  • valueYou can usetagsInstead,This parameter is meaningless, so do not need to configure
  • tagsIf there are multiple values, multiple will be generatedlist
  • @ApiOther properties configuration :(this part is copied fromhere)
The attribute name note
value urlThe path of the value
tags If you set this value,valueThe value of is overwritten
description Description of API resources
basePath The basic path
position If you configure multiple apis and 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, for example:http.https.ws.wss.
authorizations This parameter is configured for advanced feature authentication
hidden Configured totrue , will be hidden in the document
  • The instance
@api (value = "category", tags = {"category"})
@RestController
@RequestMapping("/category")
public class CategoryController {}Copy the code

@ApiOperation

  • Used inmethodson
  • saidAn HTTP request operation,Function of method
@apiOperation (value = "interface description ", httpMethod =" interface request method ", response = interface return parameter type. Class, notes = "interface issue description (method remarks) ", tags = {""});
Copy the code

Tags with multiple values generate multiple lists.

  • The instance
@apiOperation (value = "GET", httpMethod = "GET", response = Category. Class, notes = "return ", tags = {"1","2"})
Copy the code

That part comes from here

@ApiImplicitParams: used in a request method that contains a set of parameter descriptions@ApiImplicitParam: Description of a single parameter Name: parameter name value: description of the parameter required: Whether the parameter is mandatory paramType: Where the parameter is stored · query --> Obtain the request parameter:@RequestParam· Header --> Get request parameters:@RequestHeader· Path (used for restful interfaces) --> Obtain request parameters:@PathVariable· Body (request body) -->@RequestBodyUser User · Form (common form submission) dataType: Parameter type, default String, other values dataType="Integer"DefaultValue: indicates the defaultValue of the parameterCopy the code

@ApiParam

  • Used formethodson
  • parameterorfieldinstructions
@apiParam (Required = false, name = "parameter name ", value =" parameter description ")
Copy the code

Required: Indicates whether the parameter is required

  • false
  • true
  • The instance
@apiOperation (value = "new category", httpMethod = "POST", notes =" must pass json format data ", tags = {"category","insert"})
@PostMapping("addNewCategory")
public ResultVO addNewCategory(@APIParam (Required = true, name = "json", value = "JSON format, must, not null ") @RequestBody Category category) {
    return ResultVO.ok(categoryService.addNewCategory(category));
}
Copy the code

@ApiModel

  • Used forclass
  • Said toclassExplain and describe
@apiModel (value = "object name ", description =" description ")
Copy the code

Value and description can be omitted

  • The instance
@apiModel (value = "salesHistory ", description = "salesHistory ")
public class SalesHistory {}Copy the code

@apiModel has two uses:

  1. When requesting data description, i.e@RequestBodyIs used to encapsulate the request (including various validation of the data) data;
  2. When the response value is an object, i.e@ResponseBodyIs used to return a description of the value object.

Example:

  1. When requesting a data description,@RequestBodyWhen the use of
@apiModel (description = "user login ")
public class UserLoginVO implements Serializable {

	private static final long serialVersionUID = 1L;

	@APIModelProperty (value = "username ", Required =true)	
	private String username;

	@APIModelProperty (value = "password ", Required =true)	
	private String password;
	
	/ / getter/setter omitted
}
Copy the code
@API (tags=" User module ")
@Controller
public class UserController {

	@apiOperation (value = "user login ", notes = "")	
	@PostMapping(value = "/login")
	public R login(@RequestBody UserLoginVO userLoginVO) {
		User user=userSerivce.login(userLoginVO);
		returnR.okData(user); }}Copy the code

  1. @apiModelProperty: Used on JavaBean class attributes to explain the meaning of the attributes
@apiModel (description= "return response data ")
public class RestMessage implements Serializable{

	@APIModelProperty (value = "Successful ", Required =true)
	private boolean success=true;	
	
	@apiModelProperty (value = "error code ")
	private Integer errCode;
	
	@apiModelProperty (value = "prompt ")
	private String message;
	
    @apiModelProperty (value = "data ")
	private Object data;
		
	Getter/setter / * * /
}

Copy the code

@ApiModelProperty

  • Used formethods
  • rightparameter,fieldA description of the
@APIModelProperty (Required = false, value = "field description ", name =" override attribute name ", dataType = "override attribute type ", example =" hidden = false)
Copy the code
  1. required: Specifies whether the parameter is required
  • false
  • true
  1. hidden: Whether to hide
  • false
  • true
  • The instance
@apiModel (value = "salesHistory ", description = "salesHistory ")
public class SalesHistory {

    @APIModelProperty (Required = true, value = "id", name = "id", example = "zu_xt_202101011324")
    private Long id;

    @APIModelProperty (Required =true, value=" state", name="state")
    private Integer state;
    
}
Copy the code

@ApiIgnore

  • Used formethods,methods
  • Can be swaggerNot displayed on the page

No good demonstration, their own practice…

@ApiImplicitParam

  • Description of a single parameter

  • Scope: Non-object parameter description

  • For methods (for controller methods)

  • Represents a single request parameter

attribute The values role
paramType Query Parameter Type
path Submit data in the form of an address, (forrestfulInterface –> Get request parameters:@PathVariable)
query Complete automatic mapping assignment directly with parameters
body (Request body), submitted as a stream, supported onlyPOST
header Parameters inrequest headers Submit inside
form (Common form submission). The form submission is supported onlyPOST
dataType The data type of the parameter is indicated only as a flag, and is not actually validated
String The default
Long
Integer
name Parameter names
value Meaning and description of parameters
required Parameter Specifies whether to specify this parameter
true mandatory
false Not required
defaultValue The default value of the parameter
  • The instance
@apiOperation (" Query test ")
@GetMapping("select")
@apiIMPLICITParam (name="name",value=" username ",dataType="String", paramType =" query")
public void select(a){}Copy the code

@ApiImplicitParams

  • Scope: Non-object parameter set

  • For methods (for controller methods)

  • Contains a set of parameter descriptions that represent multiple individual request parameters, that is, multiple @APIIMPLICITParam

  • The instance

  @apiOperation (" Query test ")
  @GetMapping("select")
  // @apiIMPLICITParam (name="name",value=" username ",dataType="String", paramType =" query")
  @apiIMPLICITParams ({@apiIMPLICITParam (name="name",value=" username ",dataType="string", ParamType =" query",example="xingguo"), @apiimplicitParam (name="id",value=" user ID ",dataType="long", paramType =" query")})
  public void select(a){}Copy the code

@ApiResponse

  • Description of each parameter
  • code: Number, for example, 400
  • message: information, such as “Request parameters not filled in”
  • response: Class that throws an exception
  • Scope of action:Response
  • Used in@ApiResponsesIn the

@ApiResponses

  • Method returns a description of the object

  • Scope: Response set

  • Let’s use the controller method

  • That is, multiple @ApiResponse

  • Examples (examples from the network)

@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 = "request succeeded "), @apiResponse (code = 400, message =" request parameters not filled "), @apiResponse (code = 404, message = "error ")} 
	@ResponseBody
	@RequestMapping("/list")
	public JsonResult list(@RequestParam String userId) {...return JsonResult.ok().put("page", pageUtil); }}Copy the code