SpringBoot使用Springdoc OpenAPI来做Swagger文档

Springfox和Springdoc OpenAPI是两个常用的Swagger实现，各有优缺点：

Springfox

• 优点：

  • 支持Spring MVC和Spring Boot，集成简单。
  • 适合于较早的Spring Boot版本。
  • 提供了丰富的配置选项。

• 缺点：

  • 对于Spring Boot 2.6及以上版本的支持较差。
  • 在某些情况下，文档生成可能不够灵活。

Springdoc OpenAPI

• 优点：

  • 与OpenAPI 3.0标准兼容，提供更好的文档支持。
  • 对Spring Boot 2.6及以上版本的支持较好。
  • 自动生成API文档，配置简单。

• 缺点：

  • 对某些特性（如自定义请求参数）可能不如Springfox灵活。

总结

如果你使用的是较新版本的Spring Boot，建议使用Springdoc OpenAPI，因为它对新特性支持更好。如果项目较旧并且已经在使用Springfox，可以继续使用，但长期来看建议考虑迁移到Springdoc。

使用 Springdoc OpenAPI 生成 API 文档的步骤如下：

1. 添加依赖

在 pom.xml 文件中添加 Springdoc OpenAPI 的依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.14</version> <!-- 检查最新版本 -->
</dependency>

2. 配置 Spring Boot

通常情况下，Springdoc OpenAPI 可以通过简单的配置自动生成文档。你可以在 application.properties 或 application.yml 文件中添加一些基本配置（可选）：

# application.properties
springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.path=/swagger-ui.html

3. 创建 REST 控制器

编写一个简单的 REST 控制器，并使用 OpenAPI 注解来描述 API：

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;

@RestController
public class HelloController {

    @GetMapping("/hello")
    @Operation(summary = "Say hello", description = "Returns a greeting message")
    @ApiResponse(responseCode = "200", description = "Greeting message")
    public String sayHello() {
        return "Hello, World!";
    }
}

4. 访问 Swagger UI

启动 Spring Boot 应用后，可以通过访问以下 URL 查看生成的 API 文档：

• http://localhost:8080/swagger-ui.html

在这个页面上，你可以查看 API 列表、请求参数以及响应示例等信息。

5. 进一步配置

如果需要更复杂的配置，例如安全性、参数描述等，可以参考 Springdoc OpenAPI 的官方文档 获取更多信息和示例。

这样，你就可以轻松使用 Springdoc OpenAPI 来生成和查看 API 文档了！

在使用 Springdoc OpenAPI 时，常用的注解包括以下几种：

1. @Operation

用于描述操作（即 API 方法）。

@Operation(summary = "Get user by ID", description = "Returns a user based on the ID")

2. @ApiResponse

用于描述 API 方法的响应。

@ApiResponse(responseCode = "200", description = "Successful operation")
@ApiResponse(responseCode = "404", description = "User not found")

3. @ApiResponses

用于批量描述多个响应。

@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "Successful operation"),
    @ApiResponse(responseCode = "404", description = "User not found")
})

4. @Parameter

用于描述方法参数。

@Parameter(name = "id", description = "ID of the user to be retrieved", required = true)

5. @RequestBody

用于描述请求体的内容。

@RequestBody(description = "User object that needs to be added", required = true)

6. @Schema

用于定义模型的属性。

@Schema(description = "User model")
public class User {
    @Schema(description = "User ID")
    private Long id;

    @Schema(description = "User name")
    private String name;
}

7. @Tag

用于给一组 API 方法加标签，便于分类。

@Tag(name = "User", description = "Operations related to users")

示例代码

下面是一个包含以上注解的示例控制器：

import org.springframework.web.bind.annotation.*;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.ResponseSchema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;

@RestController
@RequestMapping("/users")
@Tag(name = "User", description = "Operations related to users")
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "Get user by ID", description = "Returns a user based on the ID")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "Successful operation"),
        @ApiResponse(responseCode = "404", description = "User not found")
    })
    public User getUserById(
        @Parameter(description = "ID of the user to be retrieved", required = true)
        @PathVariable Long id) {
        // Logic to get user by ID
    }

    @PostMapping
    @Operation(summary = "Add a new user", description = "Creates a new user")
    public User addUser(
        @RequestBody(description = "User object that needs to be added", required = true) User user) {
        // Logic to add user
    }
}

通过使用这些注解，可以更清晰地描述 API 接口及其行为，提升生成文档的质量。