注意
一下基于spring-boot 3.0.2
版本,该版本不支持springfox-swagger2 2.9.2
会报错,无法访问swagger
安装
在pomx
文件中添加对应的依赖
<!-- swagger --><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.1.0</version> <!-- 确保使用与 Spring Boot 兼容的最新版本 --></dependency>
新版本不需要配置类,安装好依赖后,启动项目,可以直接访问http://localhost:8080/swagger-ui/index.html
效果图:
常用语法
修改文档信息
如果需要修改文档信息,则需要使用配置类
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration
public class OpenApiConfig {@Beanpublic OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("API 文档标题") // 设置 API 文档标题.description("这是 API 文档的描述") // 设置 API 文档描述.version("1.0.0") // API 文档版本.contact(new Contact().name("开发者姓名").email("开发者邮箱").url("开发者个人网站或公司网站")).license(new License().name("Apache 2.0").url("https://springdoc.org"))); // 设置开源协议信息}
}
目录结构
效果
controller信息配置
controller添加描述信息
修改前
修改后
@Controller
@RequestMapping("/user")
@Tag(name="用户控制器",description = "处理用户相关操作")
public class UserController {@Autowiredprivate UserService userService;// 根据用户id查询用户信息@Operation(summary = "根据id获取用户",description = "返回用户信息")@GetMapping("/findById")@ResponseBodypublic Result findById(Integer id) {User user = userService.findById(id);return new Result(0, "查询成功", user);}
}
@Tag
:用于为整个控制器添加描述信息,可以指定控制器的名称 (name
) 和描述 (description
)。@Operation
:用于为具体的 API 操作(方法)添加摘要 (summary
) 和详细描述 (description
)。
入参描述
简单参数
@Operation(summary = "根据id获取用户",description = "返回用户信息")@GetMapping("/findById")@ResponseBodypublic Result findById(@Parameter(description = "用户id") Integer id) {User user = userService.findById(id);return new Result(0, "查询成功", user);}
复杂对象入参
需要在参数实体类中添加
class UserParam {@Schema(description = "用户的唯一标识符,list集合", example = "[12345]")private List<Integer> idList;
}
返回值描述
在返回值的实体类中使用@Schema
注解
public class Result<T> {@Schema(description = "业务状态码 0-成功 1-失败")private Integer code;//业务状态码 0-成功 1-失败@Schema(description = "提示信息")private String message;//提示信息...
}
需要注意的是controller
接口的返回值要指定具体的实体类,否则swagger
里无法显示
正确
@Operation(summary = "根据id获取用户", description = "返回用户信息")@GetMapping("/findById")@ResponseBodypublic Result<User> findById(@Parameter(description = "用户id") Integer id) {User user = userService.findById(id);return Result.success(user);}
错误(不影响代码运行,但是没有具体的返回值)
@Operation(summary = "根据id获取用户", description = "返回用户信息")@GetMapping("/findById")@ResponseBodypublic Result findById(@Parameter(description = "用户id") Integer id) {User user = userService.findById(id);return Result.success(user);}