返回

SpringBoot 携手 Swagger 3，打造 API 文档利器！

后端

在这个 API 繁荣的时代，对 API 文档的需求也日益高涨。而 Swagger，作为 API 文档的重量级选手，以其强大、灵活的功能备受推崇。在 Spring Boot 的加持下，Swagger 3 如虎添翼，让我们轻松创建出功能齐全、信息丰富的 API 文档。本文将带你领略 Spring Boot 与 Swagger 3 的强强联手，开启 API 文档的新篇章。

整合 Swagger 3

首先，我们需要在 Spring Boot 项目中引入 Swagger 3 的依赖项：

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>

接下来，启用 Swagger 3 的配置：

@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();
    }
}

使用注释添加元数据

Swagger 3 充分利用了注释的力量，让我们可以轻松地为 API 方法添加元数据：

@ApiOperation(value = "获取用户信息", notes = "根据用户 ID 获取用户信息")
@ApiResponses(value = {
        @ApiResponse(code = 200, message = "成功"),
        @ApiResponse(code = 404, message = "用户不存在")
})
@GetMapping("/user/{id}")
public User getUser(@PathVariable Long id) { ... }

生成 OpenAPI 规范

Swagger 3 还支持生成 OpenAPI 规范，它是一种 RESTful API 的标准化格式：

http://localhost:8080/v3/api-docs

最小化使用

为了提高性能，我们可以最小化 Swagger 3 的使用，仅在开发和测试环境中启用它：

springfox.documentation.enabled=false

结语

Spring Boot 与 Swagger 3 的结合为我们提供了强大的工具，可以高效地创建出全面、易于理解的 API 文档。通过整合 Swagger 3，我们可以节省大量的时间和精力，让 API 文档工作变得更加轻松愉快。希望本文能助你轻松驾驭 Spring Boot 和 Swagger 3，打造出令人惊艳的 API 文档！