在现代的微服务架构中,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。