springboot3 knife4j在线接口API文档篇

前言

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 · 集Swagger2及OpenAPI3为一体的增强解决方案. | Knife4j

一、依赖项：

<!-- 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

*还支持在线调试非常方便，前后端对接效率提升巨大。