一、概述
Swagger 是一个开源的 API 设计工具，其主要目的是方便开发者设计、构建、文档化和测试 RESTful API。Swagger 在多个平台上可用，包括 Java、Node.js、JavaScript 等。Swagger 3 是 Swagger 的最新版本，其相比于 Swagger 2 有了很多重大的更新和更新。Spring Boot 是基于 Spring 框架开发的，具有零配置（约定优于配置）的特点，能够快速地创建独立的、产品级的 Spring 应用程序。Spring Boot 与 Swagger 3 完美结合，可以为我们提供更加方便、高效的开发体验，本文将详细介绍 Spring Boot + Swagger 3 的使用指南。
二、安装和配置 Swagger 3
在使用 Swagger 3 前，需要在项目的 pom.xml 文件中添加以下依赖，此处我们使用的是最新版本的 swagger 依赖:
<dependencies>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
</dependencies>接下来，我们需要在 Spring Boot 应用程序中配置 Swagger。对于 Spring Boot，我们需要创建一个配置类，并使用 @Configuration 注释标记它，此外，@EnableSwagger2WebMvc 注解还需要添加，在配置类中，我们还需要配置文档的基本信息和 API 信息：
@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot Swagger 3 Demo API")
.description("Spring Boot Swagger 3 Demo API 文档")
.version("1.0")
.build();
}
}上述配置代码用以定义我们的 Swagger 文档信息。在这里，我们使用了 Docket API 定义，其中配置了 Spring Boot 应用程序的基类型（.basePackage("com.example.demo.controller")），以便找到需要暴露为 RESTful 的控制器。然后，我们还需要创建一个 apiInfo() 方法，来设置文档的基本信息和 API 信息，可以设置 API 的标题、描述和版本等信息。
三、Swagger 3 注解详解
Swagger 3 中有很多注解，这些注解可以帮助我们更好地组织、描述和文档化 RESTful API。下面，我们来了解一下这些注解，并给出使用代码示例。
1. @Api
该注解用于描述控制器类，可以设置 API 的基本信息，包括其标题、描述、版本等。示例：
@RestController
@Api(tags = "用户管理")
@RequestMapping("/user")
public class UserController {
//...
}2. @ApiOperation
该注解用于描述单个方法，可以设置方法的返回值类型、请求方式、请求地址、方法的作用、参数说明等信息。示例：
@ApiOperation(value = "获取用户列表", notes = "所有用户的列表")
@GetMapping("/list")
public List<User> list() {
//...
}3. @ApiParam
该注解用于描述方法中的参数，可以设置参数的名称、类型、样例值、是否必填、参数描述等信息。示例：
@ApiImplicitParams({
@ApiImplicitParam(name = "name", value = "姓名", dataType = "String", paramType = "form", required = true),
@ApiImplicitParam(name = "age", value = "年龄", dataType = "int", paramType = "form", required = true),
})
@PostMapping("/add")
public void addUser(@RequestParam String name, @RequestParam int age) {
//...
}四、Swagger 3 的使用示例
我们以一个简单的 Spring Boot RESTful API 作为例子，来介绍 Swagger 3 的使用。示例代码如下：
1. 项目结构
项目的目录结构示例如下：
my-project ├── src │ ├── main │ │ ├── java │ │ │ └── com.example.demo │ │ │ ├── controller // 控制器层 │ │ │ ├── entity // 实体类 │ │ │ └── swagger // Swagger 配置 │ │ └── resources │ │ ├── application.properties // 配置文件 │ │ ├── static │ │ └── templates │ └── test │ └── java │ └── com.example.demo └── pom.xml // 项目依赖
2. 引入 Swagger 3 依赖
在 pom.xml 文件中，我们需要添加如下依赖：
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
</dependencies>3. 配置 Swagger 3
创建 Swagger 配置类 SwaggerConfig.java，如下：
@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot Swagger 3 Demo API")
.description("Spring Boot Swagger 3 Demo API 文档")
.version("1.0")
.build();
}
}4. 编写控制器
新建 UserController.java，如下：
@RestController
@RequestMapping("/user")
@Api(tags = "用户管理")
public class UserController {
@ApiOperation(value = "获取用户列表", notes = "所有用户的列表")
@GetMapping("/list")
public List<User> list() {
//...
}
@ApiOperation(value = "添加用户", notes = "根据 User 对象添加用户")
@ApiImplicitParam(name = "user", value = "用户信息", dataType = "User", paramType = "body")
@PostMapping("/add")
public void addUser(@RequestBody User user) {
//...
}
@ApiOperation(value = "更新用户", notes = "根据 User 对象更新用户")
@ApiImplicitParam(name = "user", value = "用户信息", dataType = "User", paramType = "body")
@PutMapping("/update")
public void updateUser(@RequestBody User user) {
//...
}
@ApiOperation(value = "删除用户", notes = "根据 id 删除用户")
@ApiImplicitParam(name = "id", value = "用户 ID", dataType = "Long", paramType = "path")
@DeleteMapping("/{id}")
public void deleteUser(@PathVariable Long id) {
//...
}
}5. 编写实体类
新建 User.java，如下：
@Data
public class User {
private Long id;
private String name;
private Integer age;
}6. 运行应用程序
在项目根目录下运行 mvn spring-boot:run 启动应用程序，然后浏览器访问 http://localhost:8080/swagger-ui/ 即可查看接口文档。
总结
本文主要介绍了 Spring Boot 和 Swagger 3 的集成使用，其中包括了 Swagger 3 的注解详解。通过本文的介绍，相信您能够轻松上手并熟练使用 Swagger 3，为我们的 RESTful API 开发带来便利，提高了开发效率。
