SpringBoot3使用Swagger3

版本

springboot3.4.2 + JAVA 17

一、引入Swagger3依赖

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

二、快速启动

1.在application.yml中配置

# swagger-ui custom path
springdoc:swagger-ui:path : /swagger-ui.html

2.或者properties文件,则配置

# swagger-ui custom path

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

3.启动项目访问swagger

访问http://localhost:9090/swagger-ui/index.html#/

其中的9090 改成你项目后端使用的端口，注意不能省略后面的index.html

三、使用注解标注接口

Swagger配置文件

package com.sumo.ipd.config;import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration
public class Swagger3Config {@Beanpublic OpenAPI springOpenAPI() {// 访问路径：http://localhost:9090/swagger-ui/index.htmlreturn new OpenAPI().info(new Info().title("SpringDoc API").description("SpringDoc Simple Application").version("0.0.1"));}
}

Swagger2 和 Swagger3 使用的是完全不同的两套注解，所以原本使用 Swagger2 相关注解的代码页需要完全迁移，改为使用 Swagger3 的注解。

Swagger2	Swagger3
@Api	@Tag
@ApiOperation	@Operation
@ApiImplicitParams	@Parameters
@ApiImplicitParam	@Parameter
@ApiModel	@Schema
@ApiModelProperty	@Schema
@ApiResponses	@ApiResponses
@ApiResponse	@ApiResponse
@ApiIgnore	@Hidden 或者其他注解的 hidden = true 属性

举例五种常用

@Api

Swagger2 代码

@Api(value = "用户接口", tags = "UserController")

Swagger3 代码

@Tag(name = "UserController", description = "用户接口")

@ApiOperation

Swagger2 代码

@ApiOperation(value = "查询用户数据")

Swagger3 代码

@Operation(description = "查询用户数据")

@ApiImplicitParam

Swagger2 代码

@ApiImplicitParams({@ApiImplicitParam(name = "currentPage", value = "当前页码", dataTypeClass = Integer.class, required = true),@ApiImplicitParam(name = "size", value = "当前页大小", defaultValue = "10", dataTypeClass = Integer.class),@ApiImplicitParam(name = "queryUser", value = "用户查询条件", dataTypeClass = User.class)
})

Swagger3 代码

@Parameters({@Parameter(name = "currentPage", description = "当前页码", required = true),@Parameter(name = "size", description = "当前页大小", example = "10"),@Parameter(name = "queryUser", description = "用户查询条件")
})