前言
springboot3相当于springboot2很多以往正常的依赖都无法直接使用,由于oracle开源协议的更新javax变成了Jakarta,所有依赖项从 Java EE 迁移到 Jakarta EE API。
例如我们之前最常用的swagger,swagger2,已经不支持springboot3了!但其实swagger只是改了名字,现在叫做OpenAPI。
OpenAPI 3.0.0 是 OpenAPI 规范的第一个正式版本,因为它是由 SmartBear Software 捐赠给 OpenAPI Initiative,并在2015年从 Swagger 规范重命名为 OpenAPI 规范。
目前的在线文档方案都是基于open api doc实现的,比如knife4j,就是国产非常好用的一款ui加强的OpenAPI。
一、依赖项:
<!-- knife4j-openapi3 -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.3.0</version>
</dependency>
二、配置类:
@Configuration
public class SpringDocConfigurationByGjy {
@Bean
public OpenAPI springShopOpenAPI() {
return new OpenAPI()
.info(new Info().title("在线文档 API")
.description("文档描述")
.version("v1.0.0")
.license(new License().name("Apache 2.0").url("http://springdoc.org")))
.externalDocs(new ExternalDocumentation()
.description("SpringShop Wiki Documentation")
.url("https://springshop.wiki.github.org/docs"));
}
}
三、配置文件:
此配置一定要开启才会生效!
knife4j:
enable: true
四、配置注解:
注解 | 注解说明 |
---|---|
@Tag(name = “接口类描述”) | Controller 类 |
@Operation(summary =“接口方法描述”) | Controller 方法 |
@Parameters | Controller 方法 |
@Parameter(description=“参数描述”) | Controller 方法上 @Parameters 里Controller 方法的参数 |
@Parameter(hidden = true) 、@Operation(hidden = true)@Hidden | 排除或隐藏api |
@Schema | DTO实体DTO实体属性 |
@Tag(name = "用户模块", description = "用户操作的API集合")
@RestController
@RequestMapping("/user")
public class UserController {
@Operation(summary = "根据id获取用户姓名")
@GetMapping("/{id}")
public Object getById(@PathVariable("id") String id) {
UserVO userVO = new UserVO();
userVO.setId(id);
userVO.setName("小明");
userVO.setAge(1);
return userVO;
}
}
五、接口文档地址:
baseurl+/doc.html
*还支持在线调试非常方便,前后端对接效率提升巨大。