swagger 配置注解详解

话不多说：
↓↓↓
↓↓↓

• @Api：用在类上，说明类的作用

  • tags：“标签，可以在UI界面上看到的注解”
  • value：url的路径值，在类上使用的路由，如果类上没有配置，此注解无效
  • position：如果配置多个Api 想改变显示的顺序位置
  • protocols：协议
  • hidden：配置为true 将在文档中隐藏
  • produces：返回的文件的MIME类型，例如application/json,application/xml
  • consumes：需要的文件的MIME类型，
  • authorizations：认证

• @ApiSort：排序

  • value：int值

• @ApiOperation：用在方法上，用来给API增加方法说明。

  • value=“说明方法的用途、作用”
  • notes=“方法的备注说明”
  • tags：如果设置这个值、value的值会被覆盖
  • description：对api资源的描述
  • basePath
  • position
  • protocols
  • hidden
  • response：返回的对象，例如（Bean.class）
  • responseContainer：返回的内容，有效的 “List”, “Set” or “Map”.，其他无效
  • httpMethod：
  • code ：默认为200
  • extensions：扩展属性
  • produces：返回的文件的MIME类型，例如application/json,application/xml
  • consumes：需要的文件的MIME类型，
  • ignoreJsonView:忽略的json

• @ApiImplicitParam：用来注解来给方法入参增加说明。

  • paramType:参数存在的位置，该参数不能乱写，否者测试时会调用失败
    • header：请求参数放置于Request Header，使用@RequestHeader获取
    • query：请求参数放置于请求地址，使用@RequestParam获取
    • path：（用于restful接口）–>请求参数的获取：@PathVariable
    • body：@RequestBody
    • form：表单提交
  • name：参数名
  • dataType：参数类型
  • required：参数是否必须传（bool类型）
  • value：说明参数的意思
  • defaultValue：参数的默认值
  • allowableValues：允许的值
  • allowMultiple：是否允许多选
  • allowEmptyValue：允许为空？
  • readOnly：只读？

• **@ApiImplicitParams **: 用在方法上包含一组参数说明。

  • ApiImplicitParam[] value()：包含ApiImplicitParam

• @ApiResponses：用于表示一组响应

• @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

  • code：数字，例如400
  • message：信息，例如"请求参数没填好"
  • response：响应类

• @ResponseHeader：响应头设置

  • name:响应名称
  • description:描述信息
  • response:响应类
  • responseContainer:响应内容

• @ApiModel：一般用在实体类，描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候

  • @ApiModelProperty：描述一个model的属性

    示例：

    @ApiModel(value = "日志")
    public class AccessLogBean implements Serializable {
        /**
         * 编号
         */
        @ApiModelProperty("编号")
        @Setter
        @Getter
        private int id;
        /**
         * 响应码
         */
        @ApiModelProperty("响应码")
        @Setter
        @Getter
        private String code = "";
        /**
         * 请求主机地址
         */
        @ApiModelProperty("请求主机地址")
        @Setter
        @Getter
        private String ip = "";
    
    

• ApiParam：使用在参数上（和ApiImplicitParam使用其一即可）

  参数	意义
  name	属性名称
  value	属性值
  defaultValue	默认属性值
  allowableValues	可以不配置
  required	是否属性必填
  access
  allowMultiple	默认为false
  hidden	隐藏该属性
  example