Swagger 2 & 3 的区别
依赖
代码语言：html复制Swagger 2
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>代码语言：html复制Swagger 3
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>启用方式
代码语言：java复制Swagger 2
@EnableSwagger2代码语言：java复制Swagger 3
@EnableOpenApi访问方式
Swagger 2：ip:port/swagger-ui.html Swagger 3：ip:port/swagger-ui/index.html
配置
Doucument 类型
Swagger 2：DocumentationType.SWAGGER_2 Swagger 3：DocumentationType.OAS_30
示例
代码语言：java复制 @Bean
public Docket docket(Environment environment) {
return new Docket(DocumentationType.OAS_30)
// 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
.apiInfo(apiInfo())
// 是否开启
.enable(environment.getActiveProfiles().length > 0 && "dev".equals(environment.getActiveProfiles()[0]))
// 选择那些路径和api会生成document
.select()
// 扫描所有有注解的api，用这种方式更灵活
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
// 扫描指定包中的swagger注解
//.apis(RequestHandlerSelectors.basePackage("com.example.controller"))
// 指定路径处理 PathSelectors.any() 代表所有的路径
//.paths(PathSelectors.any())
.paths(PathSelectors.ant("/api/.*"))
// 创建
.build()
// 定义组
.groupName("api")
.pathMapping("/");
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("标题")
.description("API说明")
.contact(new Contact("name", "url", "email"))
.version("1.0.0")
.build();
}注解
@Api：请求类的说明
代码语言：java复制@Api(value = "", tags = "", produces = "", consumes = "", protocols = "", authorizations = @Authorization(""), hidden = false)属性名称 | 说明 |
|---|---|
value | url 的路径值 |
tags | 该类的作用 |
produces | 对 Api 资源的描述 |
consumes | 如, “application/json, application/xml” |
protocols | 协议类型，如: http, https, ws, wss. |
authorizations | 高级特性认证时配置 |
hidden | 配置为 true ，将在文档中隐藏 |
@ApiOperation：方法的说明
代码语言：java复制 @ApiOperation(value = "", notes = "", tags = "", response = Void.class, responseContainer = "", responseReference = "", httpMethod = "", nickname = "", produces = "", consumes = "", protocols = "", authorizations = @Authorization(""), hidden = false,responseHeaders =@ResponseHeader(
name = "",
response = Void.class
),code = 200,extensions =@Extension(
properties = {@ExtensionProperty(
name = "",
value = ""
)}
),ignoreJsonView = false )属性名称 | 说明 |
|---|---|
value | 说明方法的作用 |
notes | 方法的备注说明 |
tags | tag 列表，可用于按自愿或任何其它限定符对操作进行逻辑分组 |
response | 接口返回类型 |
responseContainer | 声明包装响应的容器。有效值为 List,Set,Map，任何其它值都将被忽略 |
responseReference | 指定对响应类型的引用，本地/远程引用，并将覆盖任何其它指定的 response()类 |
httpMethod | 请求方式:“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”,如果未指定则使用除"PATH"之外的其它所有 |
nickname | 第三方工具使用 operationId 来唯一表示此操作 |
produces | 采用逗号分隔的 content types 类型的返回数据，例如:application/json,application/xml |
consumes | 采用逗号分隔的 content types 类型的入参数据类型，例如:application/json,application/xml |
protocols | 指定协议类型:http,https,ws,wss,多个协议使用逗号进行分隔 |
authorizations | 获取此操作的授权列表 |
hidden | 是否隐藏操作列表中的操作 |
responseHeaders | 指定 response header 信息列表 |
code | HTTP 返回状态码 |
extensions | 可选的扩展数组 |
ignoreJsonView |
@ApiImplicitParams：用在请求的方法上，包含多 @ApiImplicitParam 或者 @ApiParam
代码语言：java复制@ApiImplicitParams(value = {})属性名称 | 说明 |
|---|---|
value | API 可用的参数列表（@ApiImplicitParam） |
@ApiImplicitParam：用于方法，表示单独的请求参数
代码语言：java复制 @ApiImplicitParam(name = "", value = "", defaultValue = "", allowableValues = "", required = false, access = "", allowMultiple = false, dataType = "", dataTypeClass = Void.class, paramType = "", example = "", examples = @Example({@ExampleProperty(
mediaType = "",
value = ""
)}), type = "", format = "", allowEmptyValue = false, readOnly = false, collectionFormat = "")属性名称 | 说明 |
|---|---|
name | 参数名称(实体类字段名称) |
value | 参数简要说明 |
defaultValue | 描述参数的默认值 |
allowableValues | 限制此参数接收的值，可使用的值或值得范围 |
required | 指定是否为必填参数,false:非必传参数; true:必传参数 |
access | 参数过滤，参考: io.swagger.core.filter.SwaggerSpecFilte |
allowMultiple | 指定参数是否可以通过多次出现来接收多个值 |
dataType | 参数的数据类型，可以使类名或原始数据类型 |
dataTypeClass | 参数的类，如果提供则覆盖 dataType |
paramType | 参数的参数类型，有效值为 path, query, body, header, form |
example | 非请求体(body)参数的单个请求示例 |
examples | 参数示例，仅适用于 BodyParameters(请求体类型的) |
type | 添加覆盖检测到的类型的功能 |
format | 添加提供自定义格式的功能 |
allowEmptyValue | 添加将 format 设置为空的功能 |
readOnly | 添加被指定为只读的能力 |
collectionFormat | 添加使用 array 类型 collectionFormat 的功能 |
@ApiParam：用于方法，参数，字段说明 表示对参数的要求和说明
代码语言：java复制@ApiParam(name = "", value = "", defaultValue = "", allowableValues = "", required = false, access = "", allowMultiple = false, hidden = false, example = "", examples = @Example({@ExampleProperty(
mediaType = "",
value = ""
)}), type = "", format = "", allowEmptyValue = false, readOnly = false, collectionFormat = "")属性名称 | 说明 |
|---|---|
name | 参数名称，参数名称将从 filed/method/parameter 名称中派生，但你可以覆盖它，路径参数必须始终命名为它们所代表的路径部分 |
value | 参数简单描述 |
defaultValue | 描述参数默认值 |
allowableValues | 可接收参数值限制，有三种方式,取值列表，取值范围 |
required | 是否为必传参数, false:非必传; true:必传 |
access | 参数过滤，请参阅:io.swagger.core.filter.SwaggerSpecFilter |
allowMultiple | 指定参数是否可以通过多次出现来接收多个值 |
hidden | 隐藏参数列表中的参数 |
example | 非请求体(body)类型的单个参数示例 |
examples | 参数示例，仅适用于请求体类型的请求 |
type | 添加覆盖检测到的类型的功能 |
format | 添加提供自定义 format 格式的功能 |
allowEmptyValue | 添加将格式设置为空的功能 |
readOnly | 添加被指定为只读的能力 |
collectionFormat | 添加使用 array 类型 collectionFormat 的功能 |
@ApiModel：用于响应实体类上，用于说明实体作用
代码语言：java复制@ApiModel(value = "", description = "", parent = Void.class, discriminator = "", subTypes = {}, reference = "")属性名称 | 说明 |
|---|---|
value | 为模型提供备用名称 |
description | 提供详细的类描述 |
parent | 为模型提供父类以允许描述继承关系 |
discriminator | 支持模型继承和多态，使用鉴别器的字段的名称，可以断言需要使用哪个子类型 |
subTypes | 从此模型继承的子类型数组 |
reference | 指定对应类型定义的引用，覆盖指定的任何其他元数据 |
@ApiModelProperty：用在属性上，描述实体类的属性
代码语言：java复制 @ApiModelProperty(value = "", name = "", allowableValues = "", access = "", notes = "", dataType = "", required = false, position = 0, hidden = false, example = "", accessMode = ApiModelProperty.AccessMode.AUTO, reference = "", allowEmptyValue = false, extensions = {@Extension(
properties = {@ExtensionProperty(
name = "",
value = ""
)}
)})属性名称 | 说明 |
|---|---|
value | 属性简要说明 |
name | 运行覆盖属性的名称。重写属性名称 |
allowableValues | 限制参数可接收的值，三种方法，固定取值，固定范围 |
access | 过滤属性，参阅:io.swagger.core.filter.SwaggerSpecFilter |
notes | 目前尚未使用 |
dataType | 参数的数据类型，可以是类名或原始数据类型，此值将覆盖从类属性读取的数据类型 |
required | 是否为必传参数,false:非必传参数; true:必传参数 |
position | 允许在模型中显示排序属性 |
hidden | 隐藏模型属性，false:不隐藏; true:隐藏 |
example | 属性的示例值 |
accessMode | |
reference | 指定对应类型定义的引用，覆盖指定的任何其他元数据 |
allowEmptyValue | 允许传空值，false:不允许传空值; true:允许传空值 |
extensions |
@ApiResponses：用于请求的方法上，根据响应码表示不同响应，包含多个 @ApiResponse
代码语言：java复制 @ApiResponses(value = {})属性名称 | 说明 |
|---|---|
value | ApiResponse 列表 |
@ApiResponse：用在请求的方法上，表示不同的响应
代码语言：java复制@ApiResponse(code = 200, message = "", response = Void.class, reference = "", responseHeaders = {@ResponseHeader(
name = "",
response = Void.class
)}, responseContainer = "", examples = @Example({@ExampleProperty(
value = "",
mediaType = ""
)}))属性名称 | 说明 |
|---|---|
code | 响应的 HTTP 状态码 |
message | 伴随响应的人类可读的消息 |
response | 用于描述消息有效负载的可选响应类，对应于响应消息对象的 schema 字段 |
reference | 指定对响应类型的引用，指定的应用可以使本地引用，也可以是远程引用，将按原样使用，并将覆盖任何指定的 response()类 |
responseHeaders | 可能响应的 header 列表 |
responseContainer | 声明响应的容器，有效值为 List,Set,Map，任何其他值都将被忽略 |
examples |
