Spring Boot集成Swagger API文档：傻瓜式零基础教程

Springfox Swagger 是一个用于构建基于 Spring Boot 的 RESTful API 文档的开源工具。它通过使用注解来描述 API 端点，自动生成易于阅读和理解的 API 文档。Springfox 通过在运行时检查应用程序，基于 Spring 配置、类结构和各种编译时 Java 注释来推断 API 语义。

在 Java 项目中使用 Springfox 有以下好处：

自动生成 API 文档：Springfox 可以帮助我们自动生成描述 API 的 JSON 文件(Swagger 2.0规范)，这使得 API 文档的编写变得非常容易和高效。
可视化 API 文档：Springfox 还提供了一个 Swagger UI，可以将 API 规范以交互式文档的形式展示出来，使得开发者和用户可以更加直观地理解和使用 API。
减少重复劳动：使用 Springfox 可以减少开发人员编写和维护 API 文档的工作量，从而提高开发效率。

需要注意的是，Springfox 3.x 版本已经移除了对 Guava 和其他第三方库的依赖，因此如果之前使用了 Guava predicates/functions，需要将其转换为 Java 8 函数接口。同时，在 SpringBoot 项目中整合 Springfox 通常需要用到两个依赖：springfox-swagger2 和 springfox-swagger-ui。

快速上手 springfox

安装依赖

如果是新项目，添加以下为 maven 依赖

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

Gradle 则添加这个

  implementation "io.springfox:springfox-boot-starter:<version>"

Swagger 配置入口


@SpringBootApplication
@EnableSwagger2 //支持 swagger 2.0 spec
@EnableOpenApi //支持 open api 3.0.3 spec
public class Application {
  public static void main(String[] args) {
    ApplicationContext ctx = SpringApplication.run(Application.class, args);
  }

  @Bean
  public PetController petController() {
    return new PetController();
  }

引入 swagger UI

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

设置 Swagger UI 静态资源目录


@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("swagger-ui.html")
      .addResourceLocations("classpath:/META-INF/resources/");

    registry.addResourceHandler("/webjars/**")
      .addResourceLocations("classpath:/META-INF/resources/webjars/");
}

试试修改 Controller

@RestController
public class CustomController {

    @RequestMapping(value = "/custom", method = RequestMethod.POST)
    public String custom() {
        return "custom";
    }
}

Entity 校验

@Entity
public class User {
    //...
    
    @NotNull(message = "First Name cannot be null")
    private String firstName;
    
    @Min(value = 15, message = "Age should not be less than 15")
    @Max(value = 65, message = "Age should not be greater than 65")
    private int age;
}

浏览器验证 Json 文件

访问 http://localhost:8080/api/v2/api-docs，如果配置没问题的话，就可以拿到 swagger spec 文件。

访问 http://localhost:8080/swagger-ui/ 看是否能够看到 Swagger UI。

Swagger UI

示例代码

以下是一个基于 Springfox Swagger 的代码示例：

@RestController
@RequestMapping("/api/v1/users")
@Api(tags = "User Management", description = "Operations for managing users")
public class UserController {

    @Autowired
    private UserService userService;

    @GetMapping("/{id}")
    @ApiOperation(value = "Get user by ID", notes = "Get the user information by user ID")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Successfully retrieved user information"),
            @ApiResponse(code = 404, message = "User not found"),
            @ApiResponse(code = 500, message = "Internal server error")
    })
    public ResponseEntity<User> getUserById(@PathVariable("id") Long id) {
        User user = userService.getUserById(id);
        if (user == null) {
            return ResponseEntity.notFound().build();
        }
        return ResponseEntity.ok(user);
    }

    @PostMapping
    @ApiOperation(value = "Create user", notes = "Create a new user with the given user information")
    @ApiResponses(value = {
            @ApiResponse(code = 201, message = "Successfully created user"),
            @ApiResponse(code = 400, message = "Invalid request body"),
            @ApiResponse(code = 500, message = "Internal server error")
    })
    public ResponseEntity<User> createUser(@RequestBody @Valid User user) {
        User newUser = userService.createUser(user);
        return ResponseEntity.created(URI.create("/api/v1/users/" + newUser.getId())).body(newUser);
    }

    @PutMapping("/{id}")
    @ApiOperation(value = "Update user", notes = "Update an existing user with the given user information")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Successfully updated user"),
            @ApiResponse(code = 400, message = "Invalid request body"),
            @ApiResponse(code = 404, message = "User not found"),
            @ApiResponse(code = 500, message = "Internal server error")
    })
    public ResponseEntity<User> updateUser(@PathVariable("id") Long id, @RequestBody @Valid User user) {
        User updatedUser = userService.updateUser(id, user);
        if (updatedUser == null) {
            return ResponseEntity.notFound().build();
        }
        return ResponseEntity.ok(updatedUser);
    }

    @DeleteMapping("/{id}")
    @ApiOperation(value = "Delete user", notes = "Delete an existing user by user ID")
    @ApiResponses(value = {
            @ApiResponse(code = 204, message = "Successfully deleted user"),
            @ApiResponse(code = 404, message = "User not found"),
            @ApiResponse(code = 500, message = "Internal server error")
    })
    public ResponseEntity<Void> deleteUser(@PathVariable("id") Long id) {
        boolean deleted = userService.deleteUser(id);
        if (deleted) {
            return ResponseEntity.noContent().build();
        }
        return ResponseEntity.notFound().build();
    }
}

在上述示例代码中，使用了多个注解来描述 API 端点，例如：

@RestController：标识该类为一个 RESTful API 的控制器。
@RequestMapping：标识该控制器中所有 API 端点的基本路径。
@GetMapping、@PostMapping、@PutMapping、@DeleteMapping：分别表示 GET、POST、PUT 和 DELETE 请求的 API 端点。
@Api：用于为该控制器中所有 API 端点添加一个描述性的标签和说明。
@ApiOperation：用于为单个 API 端点添加一个描述性的标签和说明。
@ApiResponses：用于为单个 API 端点添加一个或多个可能的响应消息。

除了上述注解之外，示例代码还包括了其他的注解，如 @PathVariable、@RequestBody、@Valid 等。这些注解用于描述 API 端点的输入参数和返回结果。

在添加了注解之后，开发人员可以使用 Springfox Swagger 来自动生成 API 文档。例如，通过访问 /v2/api-docs 端点，可以获取生成的 Swagger JSON 文件。另外，通过访问 /swagger-ui.html 端点，可以获取一个可视化的 Swagger UI 界面，用于查看和测试 API 端点。

好用的 API 开发者工具

Springfox Swagger 是一个功能强大的工具，但也有一些缺点：

学习成本高：使用 Springfox Swagger 需要掌握大量的注解和配置，这需要一定的学习成本。特别是对于初学者来说，可能需要花费更多的时间来了解和掌握 Springfox Swagger 的使用方法。
文档生成的细节有限制：虽然 Springfox Swagger 能够自动生成 API 文档，但是文档生成的细节受到限制，无法自动识别一些细节，例如 API 端点间的依赖关系、数据模型的细节等。这些需要开发者手动进行配置。
API 文档维护需谨慎：API 文档的内容需要和代码一致，如果开发者没有及时更新 API 文档，就可能导致文档和实际代码不一致，增加维护的难度。
不支持自定义文档：尽管 Springfox Swagger 提供了多种自定义主题和样式的选项，但仍存在一些自定义文档的需求无法满足。例如，开发者可能需要根据特定的需求，生成自己定制的 API 文档，而这是不容易实现的。
增加应用程序复杂度：在将 Springfox Swagger 集成到应用程序中时，需要增加一些配置和注解，这可能会增加应用程序的复杂度。这也可能会增加代码的维护成本，特别是在大型项目中。

对于开发者，我们更推荐一体化 API 工具 Apifox：Apifox 是一个接口管理、开发、测试全流程集成工具，可以通过一套系统、一份数据解决多个系统之间的 API 数据同步问题。Apifox 提供的功能包括接口文档管理、接口调试、数据 Mock、接口测试等，可以帮助团队提高效率，降低沟通成本。 此外，Apifox 还有许多创新功能，如接口支持用例管理、接口支持分组管理、多人协作编辑等，都可以提高团队的开发效率。

立即体验 Apifox

一体化 API 工具 Apifox