Spring Boot 中如何使用 Swagger

在 Spring Boot 中使用 Swagger

介绍

在开发 Web 应用时，API 文档的编写和维护是一项非常重要的工作。Swagger 是一款非常流行的 API 文档工具，可以自动生成 API 文档，并提供一系列的交互式工具，如测试界面、调试界面等，方便开发者进行 API 的调试和测试。本文将介绍如何在 Spring Boot 应用中使用 Swagger。

引入依赖

首先需要在 pom.xml 文件中引入 Swagger 的依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

上述依赖中，springfox-swagger2 是 Swagger 的核心库，提供了 API 文档的生成和管理功能；springfox-swagger-ui 则提供了 Swagger 的用户界面，包括交互式测试工具、调试工具等。

配置 Swagger

接下来需要在 Spring Boot 应用中配置 Swagger。可以通过添加一个 SwaggerConfig 类来配置 Swagger。以下是一个简单的 SwaggerConfig 配置示例：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
 
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API 文档")
                .description("这是一个 Swagger API 文档示例")
                .version("1.0.0")
                .build();
    }
 
}

上述配置中，@EnableSwagger2 注解表示启用 Swagger 功能。Docket 类表示一个 API 文档配置，可以设置 API 文档的基本信息和请求接口的过滤条件。在上述示例中，设置了 API 文档的基本信息和请求接口的过滤条件，包括 API 文档的标题、描述、版本号等信息，以及过滤掉不需要生成 API 文档的请求接口。

使用 Swagger

在 Spring Boot 应用中使用 Swagger 非常简单，只需要在需要生成 API 文档的方法上添加相应的注解即可。以下是常用的 Swagger 注解：

• @Api：表示一个 API 接口的基本信息，包括标题、描述、版本号等信息。
• @ApiOperation：表示一个 API 接口的详细信息，包括请求方法、请求路径、请求参数、请求体、响应信息等。
• @ApiParam：表示一个 API 接口的请求参数信息。
• @ApiModel：表示一个 API 接口的请求或响应模型信息。
• @ApiModelProperty：表示一个 API 接口的请求或响应模型属性信息。

以下是一个示例代码，演示如何在 Spring Boot 应用中使用 Swagger：

@RestController
@Api(tags = "用户管理")
public class UserController {
 
    @Autowired
    private UserService userService;
 
    @ApiOperation(value = "获取用户信息", notes = "根据用户 ID 获取用户信息")
    @ApiImplicitParam(name = "id", value = "用户 ID", dataType = "Long", required = true)
    @GetMapping("/user/{id}")
    public User getUserById(@PathVariable Long id) {
        return userService.getUserById(id);
    }
 
    @ApiOperation(value = "创建用户", notes = "创建一个新的用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", dataType = "String", required = true),
            @ApiImplicitParam(name = "password", value = "密码", dataType = "String", required = true)
    })
    @PostMapping("/user")
    public User createUser(@RequestParam String username, @RequestParam String password) {
        return userService.createUser(username, password);
    }
 
}

在上述示例中，使用 @Api 注解标记了 UserController类，并指定了一个标签 “用户管理”。在 getUserById 方法和 createUser 方法中，分别使用了 @ApiOperation 注解标记了方法的详细信息，包括请求方法、请求路径、请求参数、请求体、响应信息等。同时使用了 @ApiImplicitParam 注解标记了请求参数的信息，包括参数名、参数类型、是否必须等。这些注解可以帮助 Swagger 自动生成 API 文档，并提供交互式测试工具。

使用 Swagger UI

在应用启动后，可以通过访问 http://localhost:8080/swagger-ui.html 地址来打开 Swagger UI 界面。在 Swagger UI 界面中，可以看到生成的 API 文档，并提供了一系列的交互式工具，如测试界面、调试界面等，方便开发者进行 API 的调试和测试。

结语

本文介绍了如何在 Spring Boot 应用中使用 Swagger，包括引入依赖、配置 Swagger、使用 Swagger 注解和使用 Swagger UI 界面。Swagger 可以帮助开发者快速生成 API 文档，并提供一系列的交互式工具，方便开发者进行 API 的调试和测试。