Swagger2常用注解介绍

说明：本次在介绍参数时，较低版本就被遗弃的参数在此不再介绍

• @Api

  使用位置：用在请求类上，一般为controller上

  作用：表示对类的说明

  参数

  参数	类型	默认值	描述
  tags	String[]	“”	说明该类的作用，非空时会覆盖value值
  value	String	{""}	描述类的作用，基本不用，tags就够了
  produces	String	“”	设置MIME类型(output)列表，eg“application/json, application/xml”
  consumes	String	“”	设置MIME类型(input)列表，eg“application/json, application/xml”
  protocols	String	“”	设置特定协议，eg http,https,ws,wss
  authorizations	authorizations[]	{@Authorization("")}	获取授权列表
  hidden	boolean	false	隐藏设置，参数为true时则在api文挡中隐藏

  总结

  一般就用tags参数，其他的除非特殊需要

  案例

  @RestController
  @Api(tags = "用户信息管理Controller")
  @RequestMapping("/user")
  public class UserController {
      ...
  }
  

  没用tags

  

  使用tags

  

• @ApiOperation

  使用位置：用在类的请求方法上，一般就是controller内的请求方法

  作用：对方法进行说明

  参数

  参数	类型	默认值	描述
  value	String	“”	描述方法的作用
  notes	String	“”	方法的备注说明
  tags	String[]	{""}	方法描述，非空时将覆盖value值
  response	Class<?>	Void.class	响应类型
  responseContainer	String	“”	返回对象容器的声明
  responseReference	String	“”	指定对响应类型的引用
  httpMethod	String	“”	请求方式,eg get,post
  nickname	String	“”	第三方工具唯一标识
  produces	String	“”	设置MIME类型(output)列表，eg“application/json, application/xml”
  consumes	String	“”	设置MIME类型(input)列表，eg“application/json, application/xml”
  protocols	String	“”	设置特定协议，eg http,https,ws,wss
  authorizations	authorizations[]	{@Authorization("")}	获取授权列表
  hidden	boolean	false	隐藏设置，参数为true时则在api文档中隐藏
  responseHeaders	ResponseHeader[]	{@ResponseHeader( name = “”, response = Void.class )};	响应头列表
  code	int	200	HTTP状态码
  extensions	Extension[]	{@Extension( properties = {@ExtensionProperty( name = “”, value = “” )} )};	扩展属性列表

  总结

  常用参数为value和notes，value对方法进行简单说明，notes进行补充，其他参数根据需要使用

  @ApiOperation和@Api都有value和tags参数，但是常用参数不同

  @ApiOperation用value和notes进行方法说明

  @Api使用tags进行类说明

  案例

  @ApiOperation(value="获取全部用户列表", notes="不需要参数")
  @GetMapping("/getAll")
  public SwagResult getAll(){
      SwagResult result = new SwagResult();
      try{
          result.success(userService.getList());
      }catch (Exception e){
          result.error(e.getClass().getName() + ":" + e.getMessage());
          e.printStackTrace();
      }
      return result;
  }
  

  使用效果，没有使用，则没有方法说明

  

• @ApiImplicitParam

  使用位置：直接用在请求方法上，或用在请求方法上@ApilmplicitParams注解中

  作用：对一个请求参数进行说明

  参数

  参数	类型	默认值	描述
  name	String	“”	参数名，一般和解释的方法参数一致
  value	String		参数的说明
  defaultValue	String	“”	参数默认值
  required	boolean	false	是否必须传参
  access	String	“”	允许api文档中过滤参数
  allowMultiple	boolean	false	是否
  dataType	String	“”	参数数据类型，eg Integer
  dataTypeClass	Class<?>	Void.class	参数数据类型类对象
  paramType	String	“”	参数的类型 header获取时使用@RequestHeader query获取时使用@RequestParam path获取时使用@PathVariable body form
  example	String	“”	单个示例
  examples	Example	Example({@ExampleProperty( mediaType = “”, value = “” )})	参数示例，仅适用于BodyParameters
  type	String	“”
  format	String	“”
  allowEmptyValue	boolean	false	是否允许参数值为空
  readOnly	boolean	false	参数是否只读
  collectionFormat	String	“”

  总结

  常用参数为name，value，required，paramType，dataType,defaultValue等

  案例

  @ApiOperation(value="根据id获取用户信息", notes="输入String参数id来获取用户信息")
  @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "String")
  @GetMapping("/getById")
  public SwagResult getById(@RequestParam("id") String id){
      SwagResult result = new SwagResult();
      try{
          result.success(userService.getById(id));
      }catch (Exception e){
          result.error(e.getClass().getName() + ":" + e.getMessage());
          e.printStackTrace();
      }
      return result;
  }
  

  效果

  

• @ApiImplicitParams

  使用位置：直接用在请求发方法上

  作用：多个参数进行描述

  参数

  参数	类型	默认值	描述
  value	ApiImplicitParam[]		ApiImplicitParam列表

  案例

  @ApiOperation(value="根据姓名和邮件查询用户信息", notes="输入String的anme和email来获取用户信息")
  @ApiImplicitParams({@ApiImplicitParam(name = "name", value = "用户姓名", required = true, dataType = "String")
                      ,@ApiImplicitParam(name = "email", value = "用户邮箱", required = true, dataType = "String")})
  @GetMapping("/getByNameEmail")
  public SwagResult getByNameEmail(@RequestParam("name") String name,@RequestParam("email") String email){
      SwagResult result = new SwagResult();
      try{
          result.success(userService.getByNameEmail(name, email));
      }catch (Exception e){
          result.error(e.getClass().getName() + ":" + e.getMessage());
          e.printStackTrace();
      }
      return result;
  }
  

  效果

  

• @ApiParam

  使用位置：用在请求方法的括号中被描述参数的前面

  作用：参数的简要说明

  参数

  参数	类型	默认值	描述
  name	String	“”	参数名，一般和解释的方法参数一致
  value	String		参数的说明
  defaultValue	String	“”	参数默认值
  required	boolean	false	是否必须传参
  access	String	“”	允许api文档中过滤参数
  allowMultiple	boolean	false	是否
  hidden	boolean	false	参数是否隐藏
  example	String	“”	单个示例
  examples	Example	Example({@ExampleProperty( mediaType = “”, value = “” )})	参数示例，仅适用于BodyParameters
  type	String	“”
  format	String	“”
  allowEmptyValue	boolean	false	是否允许参数值为空
  readOnly	boolean	false	参数是否只读
  collectionFormat	String	“”

  总结

  因为在函数内，所以一般就只会用几个参数不会太多，太多的话可以使用@ApiImplicitParam

  案例

  @ApiOperation(value="根据姓名和邮件查询用户信息", notes="输入String的anme和email来获取用户信息")
  @GetMapping("/getByNameEmail")
  public SwagResult getByNameEmail(
      @ApiParam(name = "name", value = "用户姓名", required = true) String name
      ,@ApiParam(name = "email", value = "用户邮箱", required = true) String email){
      SwagResult result = new SwagResult();
      try{
          result.success(userService.getByNameEmail(name, email));
      }catch (Exception e){
          result.error(e.getClass().getName() + ":" + e.getMessage());
          e.printStackTrace();
      }
      return result;
  }
  

  效果

  

• @ApiResponse

  使用位置：用在请求的方法上，一般放在@ApiResponses里使用

  作用：表示一个响应信息,一般用来描述错误信息

  参数

  参数	类型	默认值	描述
  code	int		HTTP状态码
  message	String		信息
  response	Class<?>	Void.class	抛出异常的类
  reference	String	“”	响应的引用类型
  responseHeaders	ResponseHeader[]	{@ResponseHeader( name = “”, response = Void.class )}	响应头列表
  responseContainer	String	“”	响应容器类型
  examples	Example	@Example({@ExampleProperty( value = “”, mediaType = “” )})	示例

  案例1，单独使用@ApiResponse注解

  @ApiOperation(value="根据id获取用户信息", notes="输入String参数id来获取用户信息")
  @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "String")
  @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
  @GetMapping("/getById")
  public SwagResult getById(@RequestParam("id") String id){
      SwagResult result = new SwagResult();
      try{
          result.success(userService.getById(id));
      }catch (Exception e){
          result.error(e.getClass().getName() + ":" + e.getMessage());
          e.printStackTrace();
      }
      return result;
  }
  

  效果，根据结果发现并没有起作用，404 Not Found是默认的值，没有变成我们写的message信息

  

  案例2，将@ApiResponse注解放在@ApiResponses里

  @ApiOperation(value="根据id获取用户信息", notes="输入String参数id来获取用户信息")
  @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "String")
  @ApiResponses({
      @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
  })
  @GetMapping("/getById")
  public SwagResult getById(@RequestParam("id") String id){
      SwagResult result = new SwagResult();
      try{
          result.success(userService.getById(id));
      }catch (Exception e){
          result.error(e.getClass().getName() + ":" + e.getMessage());
          e.printStackTrace();
      }
      return result;
  }
  

  效果，结果发现==@ApiResponse注解放在@ApiResponses里才起作用==

  

• @ApiResponses

  使用位置：用在请求方法上

  作用：描述一组响应信息

  参数

  参数	类型	默认值	描述
  value	ApiResponse[]		ApiResponse列表

  案例见@ApiResponse注解的案例

• @ApiModel

  使用位置：用于响应类或参数类上，一般为Entity或者DTO，一般在响应数据当好是一个类的时候或者@ApiImplicitParam无法或过于复杂描述的时候

  作用：描述响应类的信息

  参数

  参数	类型	默认值	描述
  value	String	“”	描述响应类
  description	String	“”	具体描述响应类的信息作用等
  parent	Class<?>	Void.class	响应类负类的类对象
  discriminator	String	“”	鉴别器
  subTypes	Class<?>[]	{}
  reference	String	“”	响应类的引用类型

  总结

  一般就使用value和description进行描述响应类

  案例

  @ApiModel(value = "返回结果",description = "用于存储请求结果的状态及返回数据")
  public class SwagResult {
  	...
  }
  

• @ApiModelProperty

  使用位置：用在@ApiModel注解的类的属性上

  作用：对属性进行描述

  参数

  参数	类型	默认值	描述
  value	String		属性参数的说明
  name	String	“”	属性参数名
  allowableValues	String	“”	限制参数可以接收的值 以逗号分隔的列表eg “1,2” 范围值 最大/最小值
  access	String	“”	允许api文档中过滤参数
  notes	String	“”	属性参数备注信息
  dataType	String	“”	属性参数类型
  required	boolean	false	是否必须有
  position	int	0	设置不同数值，实现调整参数在api文档中的位置
  hidden	boolean	false	参数是否隐藏
  example	String	“”	单个示例
  allowEmptyValue	boolean	false	是否允许参数值为空
  readOnly	boolean	false	参数是否只读
  extensions	Extension[]	{@Extension( properties = {@ExtensionProperty( name = “”, value = “” )} )}	扩展信息列表

案例

  @ApiModel(value = "返回结果",description = "用于存储请求结果的状态及返回数据")
  public class SwagResult {
      @ApiModelProperty(value = "状态",notes = "success表示成功，error表示失败",required = true)
      private String status;
      @ApiModelProperty(value = "结果",notes = "用于存储请求结果数据",required = true)
      private Object result;
      public String getStatus() {
          return status;
      }
      public void setStatus(String status) {
          this.status = status;
      }
      public void success(Object result){
          this.status = "success";
          this.result = result;
      }
      public void error(Object result){
          this.status = "error";
          this.result = result;
      }
      public Object getResult() {
          return result;
      }
      public void setResult(Object result) {
          this.result = result;
      }
  }