【SpringDoc】SpringBoot 3 swagger-ui.html 报404 SpringDoc 官方文档问题（可能）

原创已于 2023-06-06 15:16:21 修改 · 6.5k 阅读

12 ·

CC 4.0 BY-SA版权

本博客原创文章未经允许不可用于商业盈利（包括以引流盈利的网站），纯非盈利性网站可在未经博主允许的情况下转载、使用非收费类博客，但请标明来源出处。

文章标签：

#spring boot #SpringDoc

于 2023-06-06 15:16:03 首次发布

一个bug改一天系列专栏收录该内容

13 篇文章

订阅专栏

SpringBoot3不支持旧版SpringDoc和Swagger。正确依赖是springdoc-openapi-starter-webmvc-ui。swagger-ui的正确访问路径是http://server:port/swagger-ui/index.html，而不是http://server:port/swagger-ui.html。Swagger的注解需要更新到Swagger3标准，例如将@ApiModelProperty替换为@Schema。MyBatis-Plus-Generator生成的代码需要调整@ApiModelProperty为@Schema，指定name和description属性。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

本文针对 SpringBoot 3.x 版本！！

SpringDoc v2 官方文档：https://springdoc.org/v2/

首先

旧版本的 swagger 和 1.x 版本的SpringDoc 均不支持 SpringBoot 3，所以对于 SpringBoot3 如下的两种 Swagger 或 SpringDoc 依赖均不可用，注意，是不可用

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>x.x.x</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>x.x.x</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>x.x.x</version>
</dependency>

正确的 SpringDoc 依赖

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

其次（最坑人的地方）

无数的文章甚至官方文档都表示，swagger-ui 界面的网址是 http://server:port/swagger-ui.html，访问这个网址，一直是404，天王老子来了也是404，就算在 application.properties 中设置了如下内容，也不管用：

springdoc.swagger-ui.path=/swagger-ui.html

但是打开 Demo Spring Boot 3 Web MVC with OpenAPI 3 这个官方提供的 Demo 后，显示的网址是 http://server:port/swagger-ui/index.html, 把网址换成这个，瞬间打开！！

所以，正确的解决办法就是，访问 http://server:port/swagger-ui/index.html

Swagger (SpringFox) 迁移到 SpringDoc 后注解写法补充

官方文档中仅给出了如下说明：

Replace swagger 2 annotations with swagger 3 annotations (it is already included with springdoc-openapi-starter-webmvc-ui dependency). Package for swagger 3 annotations is io.swagger.v3.oas.annotations.
@Api → @Tag
@ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
@ApiImplicitParam → @Parameter
@ApiImplicitParams → @Parameters
@ApiModel → @Schema
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
@ApiModelProperty → @Schema
@ApiOperation(value = “foo”, notes = “bar”) → @Operation(summary = “foo”, description = “bar”)
@ApiParam → @Parameter
@ApiResponse(code = 404, message = “foo”) → @ApiResponse(responseCode = “404”, description = “foo”)

但是 MyBatis-Plus-Generator 生成的代码，在 entity 属性上的注解方法是

@ApiModelProperty("密码")
private String password;

文档只告诉我，要把 @ApiModelProperty 改成 @Schema 改完就报错啊，汗。正确的改法如下：

@Schema(name = "password", description = "密码")
private String password;

其他待补充