swagger3操作手册

Swagger 3（也称为 OpenAPI 3）是一种描述 RESTful API 的规范，它提供了一种标准化的方式来描述 API 的元数据，如请求参数、响应数据、错误信息等，它还提供了一种交互式的文档界面和代码生成工具，可以帮助开发者更加方便地使用和开发 API。

下面是使用 Swagger 3 的基本步骤：

1. 引入 Swagger 3 相关依赖

在 Maven 或 Gradle 项目中，需要引入以下依赖：

<!-- Swagger 3 相关依赖 -->
<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-jaxrs2</artifactId>
    <version>2.1.5</version>
</dependency>
<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-core</artifactId>
    <version>2.1.5</version>
</dependency>

2. 在 API 接口上添加注解

使用 @Operation 注解来描述 API 接口的基本信息，使用 @Parameter 注解来描述 API 接口的请求参数，使用 @ApiResponse 注解来描述 API 接口的响应信息。

3. 配置 Swagger 相关参数

在 Spring Boot 项目中，可以在 application.yml 或 application.properties 文件中配置 Swagger 相关参数，如下所示：

# Swagger 相关配置
swagger:
  enabled: true # 是否启用 Swagger
  title: My API # API 标题
  description: My API description # API 描述
  version: 1.0.0 # API 版本号
  base-package: com.example.api # API 接口所在的包

4. 启用 Swagger

在 Spring Boot 项目中，可以使用 @EnableSwagger2 或 @EnableSwagger2WebMvc 注解来启用 Swagger。

5. 访问 Swagger UI

Swagger UI 是一个交互式的文档界面，可以通过浏览器访问，在 URL 后面添加 /swagger-ui.html 即可访问，如下所示：

http://localhost:8080/swagger-ui.html

通过以上步骤，就可以使用 Swagger 3 来描述和文档化 RESTful API 了。需要注意的是，Swagger 3 中的注解和配置与 Swagger 2 有所不同，需要注意区别。同时，Swagger 3 还提供了更多的功能和扩展性，可以根据具体需求来选择使用。