Spring Boot 3.x 引入springdoc-openapi (内置Swagger UI、webmvc-api)

接触的原因
因开发自己的项目时,写接口文档很繁琐,查到后端都在用swagger等接口工具来记录接口文档,于是学习了一下,本文记录个人配置过程,有问题欢迎指正交流??

Swagger: Swagger是一种Rest API的表示方式,它是标准的、语言无关的工具,这种表示方式不仅人可读,而且机器也可读。Swagger提供了一套完整的规范来描述API接口,包括请求和响应的数据模型、操作行为等。它通过注解或配置文件的方式与代码集成,以生成API文档。

SpringDoc: SpringDoc是基于OpenAPI 3规范的,专为Spring Boot设计的API文档生成工具。它提供了与Spring Boot更好的集成,支持Spring Boot全系列。SpringDoc利用JSR-303中的注解(如@NotNull、@Min、@Max、@Size等)来描述API的参数验证信息。此外,SpringDoc的接口信息可以通过JSON展示,也可以与Swagger-ui集成,提供可视化的API文档界面。

在网上看了许多教程,发现很多都是针对Spring Boot 2 框架的,即使有针对Spring Boot 3 的,用法也不太一样,经过对比测试,最后我使用的是 SpringDoc OpenAPI Starter WebMvc UI

它是 Spring Boot 项目中用于自动生成 API 文档的一个依赖库。它结合了 Swagger UI,提供了一个可视化的界面来展示和测试你的 RESTful APIs。这个依赖库特别适用于使用 Spring Web MVC 框架构建的项目。

这个依赖项包括了 Swagger UI 和 SpringDoc OpenAPI Starter WebMvc API,无需额外引入其他依赖即可使用。

pom.xml 配置

我的 spring boot 版本是 3.1.8
引入 springdoc 依赖(记得点击右上角的带蓝色的M按钮进行依赖下载)

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.1.8</version>
    <relativePath/> <!-- lookup parent from repository -->
&l
<think>好的,我现在要解决的问题是用户询问springdoc-openapi-uispringdoc-openapi-starter-webmvc-api之间的区别和功能对比。首先,我需要回顾一下用户提供的引用内容,看看里面有没有相关的信息。 根据引用[3]提到,springdoc-openapi依赖包含了Swagger UIWebMvc API,不需要额外引入其他依赖。这可能意味着springdoc-openapi-starter-webmvc-api是其中的一部分。而引用[4]提到,使用springdoc-openapi-starter-webmvc-ui时如果依赖版本不一致会导致404错误。这里有一个-webmvc-ui和一个-webmvc-api,用户问的是这两个的区别。 接下来,我需要明确这两个库的具体功能。通常,在Spring项目中,涉及API文档生成的库可能有不同的模块。例如,一个可能负责生成OpenAPI的元数据(API部分),另一个可能负责提供Swagger UI界面(UI部分)。例如,springdoc-openapi-starter-webmvc-api可能负责解析控制器和生成OpenAPI规范的JSON,而springdoc-openapi-ui则负责提供Swagger UI的界面展示。 另外,查看引用[2]和[3]中的依赖配置,用户提到的springdoc-openapi-starter-webmvc-ui引入,而引用[3]说该依赖包含了Swagger UIWebMvc API。可能springdoc-openapi-ui是一个更早期的模块,或者被整合到了starter中? 需要进一步核实官方文档或Maven仓库的信息。例如,springdoc-openapi的主要项目可能有不同的starter包。通常,starter-webmvc-ui可能同时包含API处理和UI界面,而starter-webmvc-api可能仅包含API处理部分,不包含UI。但需要确认。 根据经验,通常像Swagger这样的库,会有核心API模块和UI模块分开。例如,springdoc-openapi-core可能处理注解解析,生成OpenAPI数据,而springdoc-openapi-ui则负责提供Swagger UI的界面。但在starter包中,可能将这些整合到一起。例如,springdoc-openapi-starter-webmvc-ui可能是一个starter,包含UI所需的全部依赖,包括API部分,而springdoc-openapi-starter-webmvc-api可能只包含API生成部分,不包含UI。 例如,在用户提供的引用[2]中,引入的是springdoc-openapi-starter-webmvc-ui,版本2.2.0,这表明这个starter可能同时包含APIUI的依赖。而springdoc-openapi-starter-webmvc-api可能是一个更轻量的依赖,只包含生成API元数据的功能,适用于不需要UI的情况,比如仅需要生成OpenAPI JSON而不需要展示UI界面的时候。 再结合引用[4]中的问题,当使用-webmvc-ui时,如果版本不一致会导致资源找不到,这说明-webmvc-ui依赖了Swagger UI的webjar资源。而-webmvc-api可能不包含这些资源,只负责生成API文档的结构。 总结来说,两者的区别可能在于是否包含Swagger UI界面。starter-webmvc-api负责生成OpenAPI规范的数据,而starter-webmvc-ui则在此基础上添加了Swagger UI界面,方便开发者查看和测试API。因此,如果项目只需要生成OpenAPI的JSON数据,可以使用-api;如果需要UI界面,则使用-ui,后者会包含前者功能。 但需要验证这一点是否正确。例如,查看官方文档或者Maven依赖树。假设springdoc-openapi-starter-webmvc-ui依赖了springdoc-openapi-starter-webmvc-api,那么-ui会包含-api的功能,同时添加UI相关的依赖。这样,用户如果只引入-api,则无法访问Swagger UI,但可以访问/v3/api-docs端点获取OpenAPI JSON。而引入-ui后,两者都可使用。 因此,回答用户的问题时,需要明确这两个starter的区别在于是否包含Swagger UI界面,以及对应的依赖项。同时,指出使用场景:需要UI时用-ui,否则用-api。另外,可能提到在Spring Boot 3.x中,推荐使用哪个starter,比如引用[3]提到引入springdoc-openapi内置Swagger UIwebmvc-api),可能指的是starter-webmvc-ui已经整合了必要的依赖,不需要额外引入-api。 最后,确保回答结构清晰,引用相关引用内容来支持结论。</think>### springdoc-openapi-uispringdoc-openapi-starter-webmvc-api 区别与功能对比 #### 1. **功能定位** - **springdoc-openapi-starter-webmvc-api** 该模块专注于生成 OpenAPI 规范(如 JSON 格式的 API 文档元数据),负责解析 Spring WebMVC 控制器中的注解(如 `@RestController`、`@GetMapping` 等),并生成符合 OpenAPI 3.0 规范的文档数据。**不包含 Swagger UI 界面**,仅提供 API 元数据生成能力。 示例端点:`/v3/api-docs`,用于获取 JSON 格式的 API 文档[^3]。 - **springdoc-openapi-starter-webmvc-ui** 在 `webmvc-api` 的基础上,额外集成了 Swagger UI 的静态资源和配置。通过该模块,开发者可以直接访问可视化界面(如 `/swagger-ui.html`)进行 API 的交互测试和文档浏览。**包含完整的 API 元数据生成 + UI 展示功能**。 #### 2. **依赖关系** - **`webmvc-ui` 包含 `webmvc-api` 的功能** `springdoc-openapi-starter-webmvc-ui` 依赖了 `webmvc-api`,因此引入 UI 模块时无需再单独引入 API 模块。 例如,在 Maven 中只需添加: ```xml <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.2.0</version> </dependency> ``` 即可同时使用 API 文档生成和 Swagger UI 功能[^2]。 - **`webmvc-api` 独立使用场景** 如果项目仅需生成 OpenAPI 元数据(如提供给第三方集成或自动化工具),且不需要可视化界面,可单独引入 `webmvc-api` 以减少依赖体积: ```xml <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-api</artifactId> <version>2.2.0</version> </dependency> ``` #### 3. **典型配置差异** - **`webmvc-api` 的配置** 仅需设置 API 文档路径(如 `/v3/api-docs`)[^1]: ```yaml springdoc: api-docs: path: /v3/api-docs ``` - **`webmvc-ui` 的配置** 需额外配置 Swagger UI 路径和资源依赖: ```yaml springdoc: api-docs: path: /v3/api-docs swagger-ui: path: /swagger-ui.html ``` 同时需确保 `swagger-ui` 的 WebJar 版本与依赖一致,避免资源加载失败[^4]。 #### 4. **适用场景** - **选择 `webmvc-api` 的情况** - 仅需生成 OpenAPI 元数据,无需界面展示。 - 需与其他工具(如 Postman、Redoc 等)集成。 - **选择 `webmvc-ui` 的情况** - 需要本地开发和测试时快速查看、调试 API- 项目需要直接向用户提供交互式文档。 #### 5. **版本兼容性** 若使用 `webmvc-ui`,需确保其依赖的 `swagger-ui` WebJar 版本与模块声明一致,否则会导致静态资源路径错误(如 404 问题)[^4]。 ---
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值