SpringDoc OpenAPI 配置問題

簡介

OpenAPI 提供了標準化的規範,讓開發者能夠以 json 或 yaml 格式來描述 API 規格。

Springdoc OpenAPI 是一個專門為 Spring Boot REST API 自動產生 API 文件的工具,讓你不需要手動寫 Swagger 設定,就能快速生成互動式文件頁面。

參照 OpenAPI Specification(OAS)

加入依賴(Maven)pom.xml

XML 复制代码
<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>3.5.13</version>
		<relativePath/>
	</parent>
	<groupId>com.yudanny</groupId>
	<artifactId>yumicro</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>yumicro</name>
	<description/>
	<packaging>pom</packaging>
	
	<modules>
		<module>accounts</module>
</modules>

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.8.4</version>
</dependency>

註: 使用 Java x 與 Spring Boot 3.x.x,有時候 SpringDoc 可能需要相容性微調。

java 复制代码
@RestController
@RequestMapping(path = "/api", produces = { MediaType.APPLICATION_JSON_VALUE })
@AllArgsConstructor
@Validated
public class AccountsController {

    private IAccountsService iAccountsService;

    @Operation(summary = "Create an account")
    @Tag(name = "Account", description = "Account Management API")
    @PostMapping("/create")
    public ResponseEntity<ResponseDto> createAccount(@Valid @RequestBody CustomerDto customerDto) {
        iAccountsService.createAccount(customerDto);
        return ResponseEntity
                .status(HttpStatus.CREATED)
                .body(new ResponseDto(AccountsConstants.STATUS_201, AccountsConstants.MESSAGE_201));
    }

. . .

}

問題

「在多模組專案中,Parent POM 的依賴管理如何正確傳遞到子模組的 Runtime」

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

SpringDoc OpenAPI 配置問題。當你看到 "Failed to load API definition" 時,通常意味著 Swagger UI 頁面雖然跑起來了,但它去抓取後端 v3/api-docs(JSON 定義檔)時失敗了。

可檢查以下幾個點

1.檢查 API Definition 的實際路徑

Swagger UI 預設請求 /v3/api-docs。

在瀏覽器直接輸入: http://localhost:8070/v3/api-docs

如果出現 404: 代表 SpringDoc 沒有成功掃描到你的 Controller。

如果出現 JSON: 代表 Swagger UI 配置的路徑不對。

2.修正 application.yml 配置
XML 复制代码
springdoc:
  swagger-ui:
    path: /swagger-ui.html
  api-docs:
    path: /v3/api-docs
3.多模組專案的依賴問題

在多模組架構中,如果在 Parent 定義了 springdoc-openapi-starter-webmvc-ui,確保子模組 accounts 的 pom.xml 確實有繼承到這個依賴。

正常顯示

相关推荐
H.莓飛9 小时前
【C++】【STL】stack_OJ题
服务器·c语言·开发语言·数据结构·c++·算法·visual studio
学长毕设10 小时前
基于SpringBoot社区快递驿站物流配送系统-附源码
java·spring boot·后端
雾隐隐o12 小时前
优搭校园 01|项目概览、技术选型与初始化
spring boot·mysql·vue
无足鸟ICT13 小时前
【RHCA+】sosreport(收集诊断文档)
linux·运维·服务器
雪芽蓝域zzs14 小时前
第 10 章:Maven 打包
spring boot
瑞雪兆丰年兮16 小时前
Linux零基础快速入门-第二章 Linux基础命令
linux·运维·服务器
RuoyiOffice18 小时前
SpringBoot3+Vue3 采购到付款:ERP、WMS与财务如何按同一来源协同
java·spring boot·架构·vue
光电笑映19 小时前
TCP 为什么可靠?从三次握手、滑动窗口到拥塞控制全面拆解(上)
运维·服务器·网络·udp
飞奔的瓜牛19 小时前
Linux 下使用 OpenSSL 生成自签名证书完整指南
运维·服务器·nginx
企业数字化笔记19 小时前
报表上线怎么对账?口径回归、权限抽检与差异定位
java·spring boot·mysql