- Swagger3 使用教程 - 基础篇
Swagger 是一系列 RESTful API 的工具，通过 Swagger 可以获得项目的⼀种交互式 API 文档。Swagger 的目标是为 RESTful API 定义一个标准的、与语⾔言无关的接口，使人和计算机在看不到源码、或者看不到文档、或者不能通过网络流量检测的情况下，能发现和理解各种服务的功能。当服务通过 Swagger 定义，用户就能通过少量的实现逻辑与远程的服务互动。
Swagger 从 3.0 版本开始更名为 OpenAPI，通常所说的 Swagger 一般指的是 Swagger 2.x 版本，而 OpenAPI 则指的是 Swagger 3.x 版本。简而言之，Swagger2 是 OpenAPI 规范的前身，Swagger3 是 OpenAPI 规范的官方正式版本。更具体地说，Swagger3 引入了对 OpenAPI 的支持，提供了更简洁的依赖引入方式，接口地址有所改变，注解系统进行了更新，并对 Docket 配置进行了优化。Swagger3 实现了零配置和自动配置支持，同时兼容旧版注解，但文档页面地址和接口地址在不同版本间不兼容。
区别一：引入的依赖不同
- 引入 Swagger2 的依赖
- 引入 Swagger3 的依赖
区别二：使用的注解不同
- 启用注解：
- Swagger2: 使用 注解来启用 Swagger 的文档化。
- Swagger3: 使用 注解来启用 Swagger 的文档化，默认可以不使用，且在新版本中已被移除。
- 控制器注解
- Swagger2: 使用 注解来标注控制器类，表明该类的路径应该被 Swagger 文档化。
- Swagger3: 使用 注解来替代 注解。Swagger3 会使用更自然的方式来扫描类路径，自动包含所有的控制器类。
- API 描述注解
- Swagger2: 使用 和 注解来描述一个 HTTP 操作。
- Swagger3: 使用 注解来描述一个 HTTP 操作。
- 参数注解
- Swagger2: 使用 、 和 注解来描述参数。
- Swagger3: 使用 和 注解来描述参数，它提供了更丰富的属性，如 schema、example 和 content 等。
- 请求体和响应体注解
- Swagger2: 使用 和 注解来描述请求和响应的数据模型。
- Swagger3: 引入了 注解来描述数据模型，提供了更多的细节和配置选项。
- 请求响应状态注解
- Swagger2: 使用 、 注解来描述响应和错误码。
- Swagger3: 、 注解仍然可以使用，但是现在可以包含更多的信息，如媒体类型。
- 安全和授权注解
- Swagger2: 使用 注解来实现认证授权。
- Swagger3: 使用 注解来实现认证授权。
区别三：暴露的 JSON 接口不同
- Swagger2 暴露的 JSON 接口：
- Swagger3 暴露的 JSON 接口：
区别四：访问的 UI 页面路径不同
- Swagger2 的 UI 页面路径：
- Swagger3 的 UI 页面路径：
@Tag 注解
注解用于描述 Controller 的作用。
@Schema 注解
注解用于描述模型（Entity、DTO、VO）及每个属性的作用
@Operation 注解
注解用于描述方法的作用。
@Parameter 注解
注解用于描述方法参数。值得一提的是， 注解的 属性的值有 4 种：、、 和 。它们都是用来描述请求参数不在请求体内的情况下，会在哪里。比如：
-
- 配合 GET 请求 + 注解使用
- 表示参数是以 Query-String 的形式携带在 HTTP 请求地址中，即拼接在 URL 的后面，比如 。
-
- 配合 注解使用。
- 表示参数是 “藏在” HTTP 请求头中传递到后台的。
-
- 配合 注解使用
- 表示参数是 “嵌在” HTTP 请求路径中的，即属于 URL 的一部分，比如，。
-
- 表示参数是以 Cookie 的方式传递到后台的，使用较少。
GET 请求，传递 Query-String 参数
POST 请求，传递 Query-String 参数
@ApiResponse 注解
注解标注在 Controller 的方法上，用来指定 HTTP 响应信息。
@ApiResponse 单独使用
@ApiResponse 和 @ApiResponses 注解组合使用
- 引入 Swagger3 的 SpringBoot Starter
- 添加 Swagger3 的配置类
- 启动 SpringBoot 应用后，浏览器访问 Swagger3 的 UI 页面，比如 。
- Swagger3 使用
- Swagger3 注解使用指南
- Swagger2 与 Swagger3 快速入门
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容，请联系我们，一经查实，本站将立刻删除。
如需转载请保留出处：https://51itzy.com/kjqy/181717.html