swagger

swagger 注解含义思维导图，整理了Controller、vo/model/param、ApiResponses的内容，有兴趣的可以看看哟。

swagger

• Controller
  • @Api
    • 该注解将一个Controller（Class）标注为一个swagger资源（API）
    • tags API分组标签。具有相同标签的API将会被归并在一组内展示。
    • value 如果tags没有定义，value将作为Api的tags使用
  • method
    • @ApiOperation
      • 在指定的（路由）路径上，对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。
      • value 对操作的简单说明，长度为120个字母，60个汉字。
      • notes 对操作的详细说明。
      • httpMethod HTTP请求的动作名，可选值有："GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"。
      • code 默认为200，有效值必须符合标准的HTTP Status Code Definitions。
    • @ApiImplicitParams
      • 注解ApiImplicitParam的容器类，以数组方式存储。
    • @ApiImplicitParam
      • name ：参数名。
      • value ： 参数的具体意义，作用。中文说明
      • required ： 参数是否必填。
      • dataType ：参数的数据类型。
        • 参数类型，可以为类名，也可以为基本类型（String，int、boolean等）
      • paramType ：查询参数类型，这里有几种形式：
        • path 以地址的形式提交数据
          • （用于restful接口）-->请求参数的获取：@PathVariable
        • query 直接跟参数完成自动映射赋值
          • 请求参数的获取：@RequestParam
        • header 参数在request headers 里边提交
          • 请求参数的获取：@RequestHeader
        • body 以流的形式提交 仅支持POST
          • （不常用）
        • form 以form表单的形式提交 仅支持POST
          • （不常用）
      • defaultValue 参数的默认值
• vo/model/param
  • @ApiModel
    • 对model类的注解
    • value
      • model的别名，默认为类名
    • description
      • model的详细描述
  • property
    • @ApiModelProperty
      • 对model属性的注解
      • value
        • 属性简短描述
      • example
        • 属性的示例值
      • required
        • 是否为必须值
• @ApiResponses：
  • 用于表示一组响应
• @ApiResponse：
  • 用在@ApiResponses中，一般用于表达一个错误的响应信息
  • code
    • HTTP请求返回码。有效值必须符合标准的HTTP Status Code Definitions。
  • message
    • 更加易于理解的文本消息
  • response
    • 返回类型信息，必须使用完全限定类名，比如“com.xyz.cc.Person.class”。
  • responseContainer
    • 如果返回类型为容器类型，可以设置相应的值。有效值为 "List", "Set" or "Map"，其他任何无效的值都会被忽略。