Springboot3与openApi
其实OpenAPI规范（也称为 Swagger 3.x 规范）是一种用于描述RESTful API的标准化格式，它定义了如何描述API的基本信息、结构、参数、响应等方面的规范。OpenAPI规范以机器可读的方式定义了RESTful API的结构和特征，支持自动生成文档、客户端与服务端代码、Mock Server和测试工具等。
OpenAPI规范最初由开发Swagger的团队在2010年推出，从Swagger 2.0开始，Swagger规范被正式更名为OpenAPI规范，并得到了许多社区的支持和贡献。OpenAPI规范采用JSON或YAML格式编写，并支持多种数据类型，可以描述API的基本信息、路径、HTTP方法、参数、响应等各种细节。通过遵循OpenAPI规范，开发者可以快速定义和构建RESTful API，并且可以生成相应的文档和代码来帮助他们更快地开发与测试API。同时，OpenAPI规范还可以促进不同系统之间的交互和集成，因为根据规范定义的API可以被多个客户端程序和服务端程序所理解和使用。
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.1 添加依赖
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.8.4</version>
</dependency>1.2 在application.yml中添加配置
# 接口文档
springdoc:
api-docs:
enabled: true
path: /v3/api-docs
swagger-ui:
enabled: true
path: /swagger-ui.html1.3 使用注解
@OpenAPIDefinition注解用于配置接口文档的整体信息。
@SpringBootApplication
@OpenAPIDefinition(info = @Info(title = "游王子og管理平台", description = "简洁的管理系统框架，适用于常见的快速开发场景。", version = "1.0.0"))
public class App {
public static void main(String[] args) {
SpringApplication.run(App.class, args);
}
}下面案例中的注解：
- @Tag：用于标注在接口类上。
- @Operation：用于标注在接口方法上。
@Tag(name = "招商管理")
@RestController
@RequestMapping("/investmentManagement")
public class InvestmentProjectApiController {
@GetMapping("/getInvestmentProjectPage")
@Operation(summary = "获取招商项目分页数据")
public ResultResp getInvestmentProjectPage(InvestmentProjectPageReq req) {
// 此处省略
return null;
}
}数据模型注解@Schema：可以标注在类上也可以标注在属性上：
@Data
@Schema(description = "响应结果工具类")
@AllArgsConstructor
public class ResultResp {
@Schema(description = "页码")
private Integer code;
@Schema(description = "响应数据")
private Object data;
}1.4 访问接口文档
运行项目后，在浏览器输入localhost:8080/swagger-ui/index.html即可：
2 注解详细配置
2.1 @OpenAPIDefinition
@OpenAPIDefinition(
// ## API的基本信息，包括标题、版本号、描述、联系人等
info = @Info(
title = "Swagger3.0 (Open API) 框架学习示例文档", // Api接口文档标题（必填）
description = "学习Swagger框架而用来定义测试的文档", // Api接口文档描述
version = "1.2.1", // Api接口版本
termsOfService = "https://example.com/", // Api接口的服务条款地址
contact = @Contact(
name = "游王子og", // 作者名称
email = "youwangzi@qq.com", // 作者邮箱
url = "https://youwangzi.blog.csdn.net/" // 介绍作者的URL地址
),
license = @License( // 设置联系人信息
name = "Apache 2.0", // 授权名称
url = "https://www.apache.org/licenses/LICENSE-2.0.html" // 授权信息
)
),
// ## 表示服务器地址或者URL模板列表，多个服务地址随时切换（只不过是有多台IP有当前的服务API）
servers = {
@Server(url = "http://10.15.21.11/demo/", description = "本地服务器一服务"),
@Server(url = "http://10.15.21.12/demo/", description = "本地服务器二服务"),
},
externalDocs = @ExternalDocumentation(description = "更多内容请查看该链接", url = "xxx"))2.2 @Tag
@Tag 可以用于对接口进行分类和归类，便于开发人员组织和管理 API 文档。具体属性：
- name：表示标签的名称，必填属性，也得注意多个Controller上的name不要写一样的，这样就会把它们归类在一起。
- description：表示标签的描述信息，非必填属性。
- externalDocs：用于指定URL地址文档信息来追加描述接口的信息。非必填属性。
@Tag(
name = "StudentControllerAPI",
description = "学生控制器接口",
externalDocs = @ExternalDocumentation(
description = "这是一个接口文档介绍",
url = "https://youwangzi.blog.csdn.net/"))2.3 @Operation
@Operation用于对API操作（即方法）进行描述和标记。就是我们熟知的Controller下的一个个请求的方法上。具体属性：
- summary：用于简要描述API操作的概要。
- description：用于详细描述API操作的描述信息。
- parameters：用于指定API操作的参数列表，包括路径参数、请求参数、请求头部等。可以使用@Parameter注解进一步定义参数。
- operationId：用于指定API操作的唯一标识符，可以用于生成客户端代码或文档等。说明：第三方工具使用operationId来唯一标识此操作。（具体我也没用过）
- requestBody：用于定义API操作的请求体，可以使用@RequestBody注解进一步定义请求体。 说明：这里的@RequestBody注解是@io.swagger.v3.oas.annotations.parameters.RequestBody包里的
- responses：用于定义 API 操作的响应列表，包括成功响应和错误响应。可以使用@ApiResponse注解进一步定义响应。
- security：用于对API操作进行安全控制，可以使用@SecurityRequirement注解进一步定义安全需求。（后面说）
- deprecated：表示该API操作已经过时或不推荐使用。
@Operation(
summary = "根据Id查询学生信息",
description = "根据ID查询学生信息，并返回响应结果信息",
parameters = {
@Parameter(name = "id", description = "学生ID", required = true, example = "1")
},
responses = {
@ApiResponse(
responseCode = "200",
description = "响应成功",
content = @Content(
mediaType = "application/json",
schema = @Schema(
title = "AjaxResul模型",
description = "返回实体，AjaxResult内data为Student模型",
anyOf = {AjaxResult.class, StudentVO.class})
)
)
}
)2.4 @Parameter
@Parameter用于描述HTTP请求的参数信息，它是一个Parameter[]类型的数组，每个元素表示一个请求参数；
- name：参数名称。
- in：参数位置，可以是 query、header、path、cookie 等。
- description：参数描述。
- required：参数是否必须，默认为 false。
- deprecated：参数是否已过时，默认为 false。
- allowEmptyValue：是否允许空值，默认为false。
- style：参数的序列化风格，可以是 "matrix"、"label"、"form"、"simple"、"spaceDelimited"、"pipeDelimited"、"deepObject"；
- explode：当参数值是对象或数组时，是否将其展开成多个参数，默认为 false。
- schema：参数类型和格式的定义，通常使用@Schema注解。（下面介绍）
- example：参数值的示例。
parameters = {
@Parameter(name = "id", in = ParameterIn.PATH, description = "学生ID",
required = true, example = "1")
}2.5 @Schema
@Schema 是用于描述数据模型的基本信息和属性，具体属性：
- description：用于描述该类或属性的作用。
- name：指定属性名。该属性只对属性有效，对类无效。
- title：用于显示在生成的文档中的标题。
- requiredMode：用于指定该属性是否必填项。枚举Schema.RequiredMode内可选值如下：默认AUTO：可有可无；REQUIRED：必须存在此字段(会加红色*)；NOT_REQUIRED：不需要存在此字段
- accessMode：用于指定该属性的访问方式。包括AccessMode.READ_ONLY（只读）、AccessMode.WRITE_ONLY（只写）、AccessMode.READ_WRITE（读写）
- format：用于指定该属性的数据格式。例如：日期格式、时间格式、数字格式。
- example：为当前的属性创建一个示例的值，后期测试可以使用此值。
- deprecated：用于指定该属性是否为已过时的属性，默认为false。
- defaultValue：用于指定该属性的默认值。
- implementation：用于显示为该类或属性引入具体的实体路径，这代表当前指定的类或者属性将参考引入的实体。
public class Student {
...
@Schema(description = "老师信息",implementation = Teacher.class)
private Teacher teacher;
...
}