使用 Springdoc OpenAPI 为 Spring Boot 应用程序生成 Swagger文档

在现代的微服务架构中，API 文档的自动生成和管理是非常重要的。Springdoc OpenAPI 是一个强大的工具，可以与 Spring Boot 集成，用于自动生成 OpenAPI 3.0 规范的 API 文档。本文将介绍如何配置 Springdoc OpenAPI，并通过示例代码展示如何使用它生成 API 文档。

1. 配置 Springdoc OpenAPI

首先，需要在 Spring Boot 项目中添加 Springdoc OpenAPI 依赖。打开 pom.xml 文件，并添加以下依赖：

<!-- Swagger -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.8.0</version>
</dependency>

这个依赖包包含了生成和展示 API 文档所需的所有功能。

接下来，在 application.yml 或 application.properties 文件中配置 Springdoc OpenAPI。下面是配置 application.yml 文件的示例：

springdoc:
  api-docs:
    version: OPENAPI_3_0  # 配置支持的版本

这段配置指定了 Springdoc OpenAPI 使用 OpenAPI 3.0 规范来生成 API 文档。

2. 编写示例控制器

创建一个示例控制器，并使用注解来描述 API 接口。以下是一个示例控制器的代码：

package com.java.mybatisplus.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@Tag(name = "示例控制器", description = "示例控制器 API")
@RestController
@RequestMapping("/api")
public class ExampleController {
    
    

    @Operation(summary = "获取示例数据", description = "根据ID获取示例数据")
    @GetMapping("/example")
    public String getExample(@Parameter(description = "示例ID", required = true) @RequestParam String id) {
    
    
        return "示例数据: " + id;
    }
}

在上述代码中：

@Tag 注解用于为控制器类添加标签和描述。
@Operation 注解用于为接口方法添加操作的摘要和描述。
@Parameter 注解用于描述方法参数的详细信息。

3. 访问 API 文档

启动 Spring Boot 应用程序后，Springdoc OpenAPI 会自动生成并提供 API 文档。你可以通过以下 URL 访问 API 文档界面：

http://localhost:8080/swagger-ui.html（Swagger UI 页面）

在 Swagger UI 页面中，你可以查看所有的 API 端点，了解它们的请求参数和响应格式。

总结

通过配置 Springdoc OpenAPI 和使用注解描述 API，你可以轻松地为 Spring Boot 应用程序生成和管理 API 文档。这不仅有助于提高代码的可维护性，还能为开发者和用户提供清晰的 API 使用说明。希望这篇文章能帮助你更好地理解和使用 Springdoc OpenAPI。