网站建设运营知乎网站备案 价格

　　其实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: truepath: /v3/api-docsswagger-ui:enabled: truepath: /swagger-ui.html

1.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 = "[e-mail]",                  // 作者邮箱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;...}