Swagger2和openAPI3注解对比

Swagger2和Swagger3对比

swagger2	OpenAPI	注解位置
@Api	@Tag(name = “接口类名”,description = “接口类描述”)	Controller 类上
@ApiOperation	@Operation(summary =“接口方法描述”)	Controller 方法上
@ApiImplicitParams	@Parameters	Controller 方法上
@ApiImplicitParam	@Parameter(description=“参数描述”)	Controller 方法上 @Parameters 里
@ApiParam	@Parameter(description=“参数描述”)	Controller 方法的参数上
@ApiIgnore	@Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden	-
@ApiModel	@Schema	DTO类上
@ApiModelProperty	@Schema	DTO属性上

测试用例：

@Tag(name = "user-controller", description = "用户接口")
@RestController
public class UserController {
   // 忽略这个api
   @ApiIgnore
   @GetMapping("/hello")
   public String hello(){
       return "hello";
   }
  
   @Operation(summary = "用户接口 - 获取用户详情")
   @GetMapping("/user/detail")
   // 这里的@Parameter也可以不加，Swagger会自动识别到这个name参数
   // 但是加@Parameter注解可以增加一些描述等有用的信息
   public User getUser(@Parameter(in = ParameterIn.QUERY, name = "name", description = "用户名") String name){
       User user = new User();
       user.setUsername(name);
       user.setPassword("123");
       return user;
   }
  
   @Operation(summary = "用户接口 - 添加用户")
   @PostMapping("/user/add")
   // 这里的user会被Swagger自动识别
   public User addUser(@RequestBody User user){
       System.out.println("添加用户");
       return user;
   }
}

实体类：

@Schema
@Data
public class User {
  
   @Schema(name = "username", description = "用户名", defaultValue = "javalover", example = "javalover")
   private String username;

   @Schema(name = "password", description = "密码", defaultValue = "123456", example = "123456")
   private String password;

   // 隐藏这个属性，这样接口文档的请求参数中就看不到这个属性
   @Schema(hidden = true)
   private String email;

}