Of Stack

Detailed Explanation of the Use of @ ApiIgnore Annotation in Swagger

  • 2021-11-29 23:48:30
  • OfStack
The use of directory Swagger @ ApiIgnore annotation 1. When acting on a class, the whole class will be ignored 2. When acting on a method, the method will be ignored 3. When acting on a parameter, a single specific parameter will be ignored 4. Ignore the way that no fields are needed in an entity class. Use of swagger annotation analysis Swagger introduction commonly used annotation code examples

Use of Swagger @ ApiIgnore Annotations

@ ApiIgnore can be used on classes, methods, and method parameters to mask certain interfaces or parameters from being displayed on the page.

1. When applied to a class, the whole class is ignored 


@ApiIgnore
@Api(tags = {"Xxx Control class "})
@RestController
@RequestMapping("/xxx")
public class XxxController {
  ......
}

Hiding a class can also annotate its own hidden attribute with @ Api: 


@Api(value = "xxx", tags = "xxx",hidden = true)

When hidden is true, this class is hidden.

2. When acting on a method, the method is ignored 


@ApiIgnore
@ApiOperation(value = "xxx", httpMethod = "POST", notes = "xxx")
@ApiImplicitParams({
  @ApiImplicitParam(name = "xxx", value = "xxx", paramType = "query", dataType = "String", required = true)
})
@PostMapping("/xxx")
public Result importCarryEquExcel(String xxx) {
    ......
}

Hiding a method can also annotate its own hidden attribute with @ APIOperation: 


@ApiOperation(value = "xxx", httpMethod = "GET", notes = "xxx",hidden = true)

When hidden is true, this method hides.

3. When acting on parameters, a single specific parameter will be ignored 


public String abc(@ApiIgnore String a, String b, String c){
    return "a" + "b" + "c";
  }

Additional:

4. Ignore Unwanted Fields in Entity Classes

(1) Annotate its own hidden attribute with @ ApiModelProperty: 


    @ApiModelProperty(value = "xxxid", required = true,hidden = true)
    private Long id;

(2) Use the @ JsonIgnore annotation: 


    @ApiModelProperty(value = "xxxid", required = true)
    @JsonIgnore
    private Long id;

Package name: 


import  com.fasterxml.jackson.annotation.JsonIgnore;

Analysis on the Use of swagger Annotations

Introduction to Swagger

Due to the innovation of architecture, it has entered an era when the front and back ends are separated and the server only needs to provide RESTful API.

The construction of RESTful API will consider the problem of multi-terminal, so it needs to face multiple developers or even multiple development teams. In order to reduce the communication cost of docking with other teams, we usually write the corresponding API interface document.

From the earliest word document to the subsequent showdoc, many communication costs can be reduced, but the resulting problems are also troublesome. During development, the interface will change frequently due to business changes. If you need to update the interface document in real time, this is a time-consuming and laborious task.

In order to solve the above problems, Swagger came into being. He can easily integrate into the framework and generate powerful API documentation with 1 series of annotations. It can not only reduce the workload of writing documents, but also ensure the real-time update of documents. It is a better solution to maintain documents and modify codes.

Commonly used annotations

@Api() Used for classes; Represents a resource that identifies this class as swagger @ApiOperation() Used in methods; Represents the operation of 1 http request @ApiParam() Used for method, parameter and field description; Indicates the addition of metadata to parameters (description or required, etc.) @ApiModel() Used for classes Represents a description of the class, which is used for parameters to be received by entity classes @ApiModelProperty() Used for methods, fields Represents a description or data operation change to an model property @ApiIgnore() Used for classes, methods, method parameters Indicates that this method or class is ignored @ApiImplicitParam() Used in a method Represents a separate request parameter @ApiImplicitParams() Used for methods, containing multiple @ ApiImplicitParam

Code Sample

1. @ Api 


@Api(value = " User blog ", tags = " Blog interface ")
public class NoticeController { 
}

2. @ ApiOperation 


@GetMapping("/detail")
@ApiOperation(value = " Get user details ", notes = " Incoming notice" , position = 2)
public R<Notice> detail(Integer id) {
   Notice detail = noticeService.getOne(id);
   return R.data(detail );
}

3. @ ApiResponses 


@Api(value = "xxx", tags = "xxx",hidden = true)
0

4. @ ApiImplicitParams

Show in paging code

IPage < Notice > pages = noticeService.page(Condition.getPage(query), Condition.getQueryWrapper(notice, Notice.class)); 


@Api(value = "xxx", tags = "xxx",hidden = true)
1

5. @ ApiParam 


@Api(value = "xxx", tags = "xxx",hidden = true)
2

6. @ ApiModel and @ ApiModelProperty 


@Data
@ApiModel(value = "BladeUser ", description = " User object ")
public class BladeUser implements Serializable { 
   private static final long serialVersionUID = 1L; 
   @ApiModelProperty(value = " Primary key ", hidden = true)
   private Integer userId;
 
   @ApiModelProperty(value = " Nickname ")
   private String userName;
 
   @ApiModelProperty(value = " Account number ")
   private String account;
 
   @ApiModelProperty(value = " Role id")
   private String roleId;
 
   @ApiModelProperty(value = " Role name ")
   private String roleName; 
}

7. @ ApiIgnore () 


@Api(value = "xxx", tags = "xxx",hidden = true)
4
Related articles: