1.简介
OpenAPI阶段的Swagger也被称为Swagger 3.0。在Swagger 2.0后,Swagger规范正式更名为OpenAPI规范,并且根据OpenAPI规范的版本号进行了更新。因此,Swagger 3.0对应的就是OpenAPI 3.0版本,它是Swagger在OpenAPI阶段推出的一个重要版本。与前几个版本相比,Swagger 3.0更加强调对RESTful API的支持和规范化,提供了更丰富和灵活的定义方式,并且可以用于自动生成文档、客户端代码、服务器代码和测试工具等。
1.1 Open API
OpenApi是业界真正的 api 文档标准,其是由 Swagger 来维护的,并被linux列为api标准,从而成为行业标准。
OpenAPI 3 Library for spring-boot (springdoc.org)
1.2 Swagger
swagger 是一个 api 文档维护组织,后来成为了 Open API 标准的主要定义者
1.3 SpringFox
SpringFox 是一个成熟且广泛使用的库,它允许你通过注解描述 API 并生成符合 OpenAPI 规范(原 Swagger 规范)的文档。SpringFox 支持 Swagger 2.0 及其后继者 OpenAPI 3.0。
特点:
- 支持 Swagger 2.0 和 OpenAPI 3.0。
- 通过使用 Swagger 注解(如
@Api
,@ApiOperation
,@ApiModel
,@ApiModelProperty
等)来描述 API。 - 提供了多种方式来自定义文档,包括通过代码或配置文件。
- 可以通过扫描类路径中的控制器类自动生成文档。
- 更新频率较低,最近几年维护活动减少。
1.4 SpringDoc
OpenAPI 3 Library for spring-boot (springdoc.org)
SpringDoc 是一个相对较新的替代方案,它专为 OpenAPI 3.0 设计,提供了对最新 OpenAPI 规范的全面支持。
特点:
- 主要关注 OpenAPI 3.0,对 OpenAPI 3.0 的支持更全面。
- 使用更简洁的注解(如
@Tag
,@Operation
,@Parameter
等)来描述 API。 - 更好的支持 Spring WebFlux,适合现代的响应式编程模型。
- 更频繁的更新和活跃的社区支持。
- 与 Spring Boot 的集成更加紧密,可以通过 Spring Boot 的自动配置特性简化设置过程。
1.5 Knife4j
Knife4jInsight(简单、方便的OpenAPI接口文档私有化聚合平台),地址:http://knife4j.nethttp://knife4j.net/
1.6 Swagger 3 (OpenAPI 3) 与swagger 2 区别
1.7 Swagger 3 (OpenAPI 3)注解详细介绍
(1)基本信息注解 | 描述 | 位置 | 属性 |
@OpenAPIDefinition |
用于定义整个 API 文档的基本信息。 | 类、接口 |
|
@Info |
用于定义 API 文档的基本信息 | 类、接口。 |
|
@Contact |
用于定义 API 文档中的联系人信息。 | 类、接口 |
|
@License |
用于定义 API 文档中的许可证信息 | 类、接口。 |
|
(2)分组注解 | 描述 | 位置 | 属性 |
@Tag |
用于给 API 分组,用途类似于为 API 文档添加标签。 | 方法、类、接口 |
|
(3)请求方法注解 | 描述 | 位置 | 属性 |
@Operation |
用于描述 API 的操作。 | 方法。 |
|
@Parameter |
用于描述操作的输入参数。 | 方法 |
|
@RequestBody |
用于描述操作的请求体 | 方法 |
|
@ApiResponse |
用于描述操作的响应结果 | 方法 |
|
@Content |
用于描述请求体或响应的内容 | 方法。 |
|
@Schema |
用于描述数据模型的属性。 | 方法、类、接口。 |
|
(4)路径注解 | 描述 | 位置 | 属性 |
@Path |
用于定义路径参数。 | 方法 |
|
@PathVariable |
用于描述路径参数。 | 方法的参数 |
|
@RequestParam |
用于描述查询参数。 | 方法的参数。 |
|
@RequestBody |
用于描述请求体。 | 方法的参数 | |
(5) 响应注解 | 描述 | 位置 | 属性 |
@ApiResponse |
用于描述响应结果。 | 方法。 |
|
@Content |
用于描述响应结果的内容 | 方法 |
|
@Schema |
用于描述数据模型的属性。 | 方法、类、接口。 |
|
2. 配置Knife4j
2.1 添加依赖
因为Knife4j提供的starter已经引用springdoc-openapi的jar,开发者需注意避免jar包冲突。这里直接使用Knife4j
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.4.0</version>
</dependency>
2.2 添加配置类
package com.zsh.test.swagger3test.config;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.media.StringSchema;
import io.swagger.v3.oas.models.parameters.Parameter;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springdoc.core.configuration.SpringDocConfiguration;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.boot.autoconfigure.AutoConfigureBefore;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.util.Collections;
/**Knife4j整合swagger3
* @author ZhaoShuhao
* @data 2024/7/21 11:06
*/
@Configuration
public class OpenApiConfig {
@Bean
public OpenAPI springShopOpenApi() {
return new OpenAPI()
// 接口文档标题
.info(new Info().title("swagger3")
// 接口文档简介
.description("这是基于Knife4j OpenApi3的测试接口文档")
// 接口文档版本
.version("1.0版本")
// 开发者联系方式
.contact(new Contact().name("zsh")
.email("1401969521@qq.com")));
}
}
2.3 yml配置
springdoc:
swagger-ui:
path: /swagger-ui.html
tags-sorter: alpha
operations-sorter: alpha
api-docs:
path: /v3/api-docs
group-configs:
- group: 'zsh'
paths-to-match: '/**'
#生成文档所需的扫包路径,一般为启动类目录
packages-to-scan: com.zsh.test.swagger3test
#knife4j配置
knife4j:
#是否启用增强设置
enable: true
#开启生产环境屏蔽
production: false
#是否启用登录认证
basic:
enable: true
username: admin
password: 123456
setting:
language: zh_cn
enable-version: true
enable-swagger-models: true
swagger-model-name: 用户模块
2.4 运行结果
路径:http://localhost:8080/doc.html