Swagger学习
Swagger学习
Swagger 注解-@Api
Swagger 注解-@ApiOperation
Swagger 注解-@ApiImplicitParams 和 @ApiImplicitParam
Swagger 注解-@ApiModel 和 @ApiModelProperty
Swagger 注解-@ApiResponses 和 @ApiResponse
Swagger 注解-@ResponseHeader
Swagger 注解-@ApiParam
Swagger 注解-@Authorization 和 @AuthorizationScope
Swagger 注解-@SwaggerDefinition
Swagger 注解-@ExternalDocs
Springboot 集成 Swagger GitHub 地址
@Api
使用场景
在 Rest 接口类(controller)上边使用。
概述
标记类为 Swagger 资源类，运行时有效。
属性
| 属性名称 | 数据类型 | 默认值 | 说明 |
|---|---|---|---|
| value | String | “” | 隐式设置操作的标记， 遗留支持 (读取 description) |
| tags | String[] | “” | 对接口进行分组 |
| produces | String | “” | 采用逗号分隔的 content types,例如:application/json,application/xml 生成JSON和XML的输出 |
| consumes | String | “” | 采用逗号分隔的 content types，例如: application/json,application/xml 会接收JSON和XML的输入 |
| protocols | String | “” | 采用逗号分隔的可用协议，例如:http,https,ws,wss |
| authorizations | Authorization[] | “” | 授权列表 |
| hidden | boolean | false | 隐藏此资源下的操作, 和 @ApiOperation 注解中的 hidden 组合使用可以隐藏改接口 |
@ApiOperation
使用场景
在 Rest 接口(controller中的方法)上使用
概述
描述针对特定路径的操作，通常是 HTTP 方法。具有等效路径的操作被分到单个分组中。HTTP 方法和路径的组合创建了一个独特的操作
属性
| 属性名称 | 数据类型 | 默认值 | 说明 |
|---|---|---|---|
| value | String | 接口简要说明，120字符或更少 | |
| notes | String | “” | 接口详细描述 |
| tags | String[] | “” | tag 列表，可用于按自愿或任何其它限定符对操作进行逻辑分组 |
| response | Class<?> | Void.class | 接口返回类型 |
| responseContainer | String | “” | 声明包装响应的容器。有效值为 List,Set,Map，任何其它值都将被忽略 |
| responseReference | String | “” | 指定对响应类型的引用，本地/远程引用，并将覆盖任何其它指定的response()类 |
| httpMethod | String | “” | 请求方式:“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”,如果未指定则使用除"PATH"之外的其它所有 |
| nickname | String | “” | 第三方工具使用operationId来唯一表示此操作 |
| produces | String | “” | 采用逗号分隔的 content types 类型的返回数据，例如:application/json,application/xml |
| consumes | String | “” | 采用逗号分隔的 content types 类型的入参数据类型，例如:application/json,application/xml |
| protocols | String | “” | 指定协议类型:http,https,ws,wss,多个协议使用逗号进行分隔 |
| authorizations | Authorization[] | @Authorization(value = “”) | 获取此操作的授权列表 |
| hidden | boolean | false | 是否隐藏操作列表中的操作 |
| responseHeaders | ResponseHeader[] | @ResponseHeader(name = “”, response = Void.class) | 指定 response header 信息列表 |
| code | int | 200 | HTTP返回状态码 |
| extensions | Extension[] | @Extension(properties = @ExtensionProperty(name = “”, value = “”)) | 可选的扩展数组 |
@ApiImplicitParams
使用场景
在 Rest 接口方法上使用来指定请求参数
概述
在 Rest 接口方法上使用来指定请求参数
属性
| 属性名称 | 数据类型 | 默认值 | 说明 |
|---|---|---|---|
| value | ApiImplicitParam[] | API 可用的参数列表 |
@ApiImplicitParam
使用场景
场景一：在 Rest 接口上单独使用
@ApiImplicitParam 在 Rest 接口上单独使用的时候，表示单个请求参数
场景二：在 Rest 接口上和 @ApiImplicitParams 组合使用
@ApiImplicitParam 在 Rest 接口上和 @ApiImplicitParams 组合时候，表示多个请求参数
概述
表示 Rest 接口的单个请求参数，可与 @ApiImplicitParams 组合使用来表示多个请求参数
属性
| 属性名称 | 数据类型 | 默认值 | 说明 |
|---|---|---|---|
| name | String | “” | 参数名称(实体类字段名称) |
| value | String | “” | 参数简要说明 |
| defaultValue | String | “” | 描述参数的默认值 |
| allowableValues | String | “” | 限制此参数接收的值，可使用的值或值得范围 |
| required | boolean | false | 指定是否为必填参数,false:非必传参数; true:必传参数 |
| access | String | “” | 参数过滤，参考: io.swagger.core.filter.SwaggerSpecFilte |
| allowMultiple | boolean | false | 指定参数是否可以通过多次出现来接收多个值 |
| dataType | String | “” | 参数的数据类型，可以使类名或原始数据类型 |
| dataTypeClass | Class<?> | Void.class | 参数的类，如果提供则覆盖 dataType |
| paramType | String | “” | 参数的参数类型，有效值为 path, query, body, header, form |
| example | String | “” | 非请求体(body)参数的单个请求示例 |
| examples | Example | @Example(value = @ExampleProperty(mediaType = “”, value = “”)) | 参数示例，仅适用于 BodyParameters(请求体类型的) |
| type | String | “” | 添加覆盖检测到的类型的功能 |
| format | String | “” | 添加提供自定义格式的功能 |
| allowEmptyValue | boolean | false | 添加将 format 设置为空的功能 |
| readOnly | boolean | false | 添加被指定为只读的能力 |
| collectionFormat | String | “” | 添加使用 array 类型 collectionFormat 的功能 |
@ApiModel
使用场景
在实体类上边使用，标记类时表示 swagger 的解析类，常用作结果的返回值封装的对象
概述
提供有关 swagger 模型的其它信息，类将在操作中用作类型时自动内省（自动进行运行时类型检查#问题/待解决 :#？）
属性
| 属性名称 | 数据类型 | 默认值 | 说明 |
|---|---|---|---|
| value | String | 类名 | 为模型提供备用名称 |
| description | String | “” | 提供详细的类描述 |
| parent | Class<?> parent | Void.class | 为模型提供父类以允许描述继承关系 |
| discriminatory | String | “” | 支持模型继承和多态，使用鉴别器的字段的名称，可以断言需要使用哪个子类型 |
| subTypes | Class<?>[] | {} | 从此模型继承的子类型数组 |
| reference | String | “” | 指定对应类型定义的引用，覆盖指定的任何其他元数据 |
@ApiModelProperty
使用场景
使用在被 @ApiModel 注解的模型类的属性上
概述
添加和操作模型属性的数据
属性
| 属性名称 | 数据类型 | 默认值 | 说明 |
|---|---|---|---|
| value | String | “” | 属性简要说明 |
| name | String | “” | 运行覆盖属性的名称。重写属性名称 |
| allowableValues | String | “” | 限制参数可接收的值，三种方法，固定取值，固定范围 |
| access | String | “” | 过滤属性，参阅:io.swagger.core.filter.SwaggerSpecFilter |
| notes | String | “” | 目前尚未使用 |
| dataType | String | “” | 参数的数据类型，可以是类名或原始数据类型，此值将覆盖从类属性读取的数据类型 |
| required | boolean | false | 是否为必传参数,false:非必传参数; true:必传参数 |
| position | int | 0 | 允许在模型中显示排序属性 |
| hidden | boolean | false | 隐藏模型属性，false:不隐藏; true:隐藏 |
| example | String | “” | 属性的示例值 |
| readOnly | boolean | false | 指定模型属性为只读，false:非只读; true:只读 |
| reference | String | “” | 指定对应类型定义的引用，覆盖指定的任何其他元数据 |
| allowEmptyValue | boolean | false | 允许传空值，false:不允许传空值; true:允许传空值 |
浙公网安备 33010602011771号