Swagger 注解使用

Swagger 注解

Swagger中的所有注解

       首先我们通过Swagger的源码可以看到有很多的注解，下面这张截图应该可以包括swagger的所有注解。

Swagger 常用注解的说明 

 第一类： 用在类上的注解  @Api   和@ ApiModel                                                                                                                           

注解名称	使用说明
@Api	@Api 用在类上，说明该类的作用。可以标记一个 Controller 类作为 Swagger 文档资源,所以一般用在Controller接口中，在Swagger页面上说明这个接口文档
@ApiModel	使用在实体类上， 一般用来对接口入参来说明

 

 

 

 

@Api  使用 

1.  使用@Api 的代码示例

@RestController
@RequestMapping("/xxxxxx")
@Api(tags = "密保问题")
public class xxxxController extends BaseController {
}

@RestController
@RequestMapping("/xxxxxx")
@Api(tags = "认识我们")
public class xxxxController extends BaseController {
}

@RestController
@RequestMapping("/xxxxxx")
@Api(tags = "设置密码")
public class xxxxController extends BaseController {
}

2. 使用@Api 注解的效果 ，每个Controller接口进行说明该类的作用                                                                                                      

@ApiModel 使用 

1. 代码示例

@ApiModel("设置密码参数")
public class xxxParam {
}

第二类: 用来对参数进行说明的注解  @ ApiModelProperty  @ApiParam @ApiImplicitParam 和 @ApiImplicitParams

 

注解	使用说名	常用参数
@ ApiModelProperty	@ApiModelProperty()和@ApiModel 配套使用在实体类中， 用于字段，表示对 model 属性的说明	value–字段说明  name–重写属性名字  dataType–重写属性类型  required–是否必填  example–举例说明  hidden–隐藏
@ApiImplicitParam 和 @ApiImplicitParams	Api配套使用在Controller接口的方法上，对单独的参数进行说明  这两个注解一起使用，当只有一个参数修饰用@ApiImplicitParam，当有多个参参数用@ApiImplicitParams	name：参数名，对应方法中单独的参数名称。 value：参数中文说明。 required：是否必填。 paramType：参数类型，取值为 path、query、body、header、form。 dataType：参数数据类型。 defaultValue：默认值。
@ApiParam	@ApiParam 用于 Controller 中方法的参数说明。使用方式代码如下所示。	value：参数说明 required：是否必填

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

@ ApiModelProperty  代码使用

@Data
@ApiModel( description = "新增用户参数")
public class AddUserParam {
    @ApiModelProperty(value = "ID")
    private String id;
    @ApiModelProperty(value = "名称")
    private String name;
    @ApiModelProperty(value = "年龄")
    private int age;
}

@ApiParam @ApiImplicitParam 代码使用

@ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "用户ID", dataType = "string", paramType = "query", required = true, defaultValue = "1") })
@GetMapping("/user")
public UserDto getUser(@RequestParam("id") String id) {
    return new UserDto();
}

 @ApiParam 代码使用

@PostMapping("/user")
public UserDto addUser(@ApiParam(value = "新增用户参数", required = true) @RequestBody AddUserParam param) {
    System.err.println(param.getName());
    return new UserDto();
}

第三类： 用在方法上来标记方法的作用  @ApiOperation

注解	使用
@ApiOperation	@ApiOperation 用在 Controller 里的方法上，说明方法的作用，每一个接口的定义。

 

 

 

@ApiOperation 代码示例

@ApiOperation(value="新增用户", notes="详细描述")
public UserDto addUser(@ApiParam(value = "新增用户参数", required = true) @RequestBody AddUserParam param) {

}