swagger2常用注解详解

最新推荐文章于 2025-04-17 09:15:00 发布

进阶的蚂蚱

最新推荐文章于 2025-04-17 09:15:00 发布

阅读量1.5k

点赞数

分类专栏： swagger 文章标签： java 前端开发语言

本文链接：https://blog.youkuaiyun.com/littleox_frighting/article/details/125576551

版权

swagger 专栏收录该内容

2 篇文章

订阅专栏

@Api
- 作用于controller
- 常用属性
  - tags
    - 生成的api文档会根据tags分类，直白的说就是这个controller中的所有接口生成的接口文档都会在tags这个list下；tags如果有多个值，会生成多个list，每个list都显示所有接口
    - 效果展示：
  - value
    - value的作用类似tags,但是不能有多个值
    - 效果展示：
@ApiOperation
- 作用于controller中的方法
- 属性：常用value， notes
  - value
    - 相当于接口名称
  - notes
    - 接口描述
  - nickname
    - 应该是接口的昵称，但是在UI上没有体现
  - tags
    - 数组，可多个，当有多个值，该方法会在每一个值下面出现
    - 不常用
  - code
    - 不常用，未在UI上体现
  - httpMethod
    - 请求类型，UI上显示的是此处的值，调试时发送的请求类型也是按这里设定的值发送的。当设定值与方法实际接收的请求类型（@RequestMapping中设置的方法类型）不一致是会导致请求不通过(405状态码)
    - 为避免冲突，一般不设置
  - produces：基本不设置
  - consumes：基本不设置
  - hidden
    - 是否隐藏，值为true时，被修饰的方法在UI上不可见
    - 默认值false，一般不设置
      效果展示：
@ApiImplicitParams
- 只有一个ApiImplicitParam数组
- @ApiImplicitParam
  - 作用于controller方法中，可不依附于@ApiImplicitParams单独使用
  - 常用属性
    - name
      - 参数名
    - value
      - 参数的解释、说明
    - required
      - 是否必需，默认false
    - paramType
      - 表示参数应该放在请求的什么位置
      - 可选值
        header
        参数位于请求头中
        获取方式：在代码中使用接收注解@RequestHeader
        
        query
        用于get请求的参数拼接
        获取方式：在代码中使用接收注解@RequestParam
        
        path
        使用于restful接口，存在于请求路径中
        获取方式：在代码中使用接收注解@PathVariable
        
        body
        放在请求体中
        获取方式：使用@RequestBody注解
        
        form
        不常用
    - dataType
      - 参数的数据类型，可为基本数据类型及引用数据类型
    - defaultValue
      - 默认值
    - example
      - 示例
  - 示例：
    
    PS: 当使用了@RequestBody注解来接收对象参数时，不再建议使用@ApiImplicitParam注解，否则将会导致对象内部属性的介绍缺失, @RequestBody结合@ApiModel及@ApiModelProperty效果更佳。
@ApiResponses
- @ApiResponse
  - 作用于controller中的方法
  - 属性
    - code：状态码
    - message：结果说明
    - response：异常类型
  - 示例
@ApiModel
- 作用于接口相关的实体类
- 常用属性：
  - value：实体类类的名称
  - description：实体类文本信息描述
@ApiModelProperty
- 作用于接口相关的实体类中的成员变量
- 常用属性
  - name：类似于别名，不常用
  - value：参数的信息描述
  - required ：是否必需
  - hidden ：是否隐藏
  - allowEmptyValue：是否允许空置
    示例：