SpringDoc：一个用于自动生成API文档的工具

SpringDoc 是一个基于 Spring 和 OpenAPI 3.0 规范的工具，旨在为 Java 应用程序自动生成 API 文档。它提供了一种简单而有效的方式来为 RESTful API 生成交互式文档，从而使开发者能够更轻松地理解和使用 API。通过结合 Spring Boot，SpringDoc 能够自动提取控制器、请求参数、响应类型，以及其他重要信息，减少手动编写文档的繁琐工作。

为什么使用 SpringDoc

• 自动化: SpringDoc 可以自动生成文档，减少了人工维护的负担。
• 开放标准: 使用 OpenAPI 3.0 标准，提升了文档的可读性和一致性。
• 交互性: 生成的文档支持 Swagger UI，方便开发者测试 API。
• 集成简单: 与 Spring Boot 应用集成非常简单，只需少量配置即可开始使用。

如何使用 SpringDoc

1. 添加依赖

在你的 Spring Boot 项目的 pom.xml 中添加 SpringDoc 相关依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.14</version> <!-- 请根据官方文档查看最新版本 -->
</dependency>

对于 Gradle 项目，可以在 build.gradle 中添加如下依赖：

implementation 'org.springdoc:springdoc-openapi-ui:1.6.14'

2. 创建控制器

接下来，创建一个简单的 REST 控制器。例如，一个用于管理用户的控制器：

import org.springframework.web.bind.annotation.*;

import java.util.HashMap;
import java.util.Map;

@RestController
@RequestMapping("/api/users")
public class UserController {

    private final Map<Long, String> users = new HashMap<>();
    private long idCounter = 1;

    @PostMapping
    public String createUser(@RequestBody String name) {
        users.put(idCounter++, name);
        return "User created";
    }

    @GetMapping("/{id}")
    public String getUser(@PathVariable Long id) {
        return users.getOrDefault(id, "User not found");
    }

    @GetMapping
    public Map<Long, String> getAllUsers() {
        return users;
    }

    @DeleteMapping("/{id}")
    public String deleteUser(@PathVariable Long id) {
        if (users.remove(id) != null) {
            return "User deleted";
        } else {
            return "User not found";
        }
    }
}

3. 访问生成的文档

启动 Spring Boot 应用后，可以访问 http://localhost:8080/v3/api-docs 查看生成的 OpenAPI 文档。在浏览器中输入 http://localhost:8080/swagger-ui.html，你可以看到 Swagger UI 界面，能与生成的 API 进行交互。

4. 配置自定义文档信息

可以通过在 application.properties 或 application.yml 文件中配置一些自定义文档信息，例如：

springdoc.api-docs.path=/api-docs
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.swagger-ui.urls[0].name=用户API
springdoc.swagger-ui.urls[0].url=${springdoc.api-docs.path}

这会修改 API 文档的访问路径和 Swagger UI 的配置。

结论

SpringDoc 是一个强大的工具，它简化了 API 文档生成的过程。通过与 Spring Boot 的无缝集成，开发者可以专注于业务逻辑的实现，而无需担心文档的维护。无论是构建新的项目，还是对现有项目进行文档化，SpringDoc 都提供了一个极为便利的解决方案。通过简单的配置和注解，生成的 API 文档不仅完整而且易于使用。