Spring Boot项目中编写和配置Swagger接口文档

原创已于 2024-12-20 00:52:15 修改 · 666 阅读

CC 4.0 BY-SA版权

文章标签：

于 2024-12-20 00:43:30 首次发布

在Spring Boot项目中，Swagger是一个非常流行的API文档生成工具，它可以帮助开发者自动生成API文档，并且这些文档是交互式的，允许用户直接测试API。在Spring Boot中配置Swagger接口文档通常涉及添加依赖、创建配置类以及（可选地）在控制器类和方法上使用Swagger注解来丰富文档信息。以下是编写和配置Swagger接口文档的步骤：

1. 添加依赖

首先，你需要在pom.xml文件中添加Swagger的依赖。如果你使用的是Springfox（Swagger的一个Spring Boot实现），那么依赖如下：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version> <!-- 请确保使用适合你Spring Boot版本的Springfox版本 -->
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

注意：Springfox 3.x版本开始支持Spring Boot 2.x及更高版本，并且配置方式有所变化。如果你使用的是Spring Boot 2.x或更高版本，请考虑使用Springfox 3.x或更高版本，或者切换到Springdoc OpenAPI（另一个流行的Swagger实现）。

2. 配置Swagger

接下来，你需要创建一个配置类来配置Swagger。这个配置类通常使用@Configuration和@EnableSwagger2注解。

在这个配置类中，Docket对象用于定义Swagger的扫描路径和文档类型。apis方法用于指定哪些包下的控制器应该被Swagger扫描，paths方法用于指定哪些路径应该被包含在文档中。

3. 使用Swagger注解

虽然Swagger可以通过反射自动生成API文档，但使用Swagger注解可以丰富文档的信息，使其更具可读性和可用性。你可以在控制器类和方法上使用以下注解：

@Api：用于描述控制器类。
@ApiOperation：用于描述控制器中的方法。
@ApiParam：用于描述方法参数。
@ApiModel和@ApiModelProperty：用于描述模型类及其属性。

现在，你可以在你的控制器类和方法上使用Swagger提供的注解来丰富API文档的信息。例如：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;


@RestController
@Api(value = "用户控制器", tags = {"用户管理相关接口"})
public class UserController {


@GetMapping("/users")
@ApiOperation(value = "获取用户列表", notes = "根据条件获取用户列表")
public List<User> getUsers(
@ApiParam(value = "用户名", required = false) @RequestParam(required = false) String username) {
// 这里是业务逻辑代码
return new ArrayList<>(); // 示例返回空列表
}
}