当前位置：首页 > article >正文

Knife4j与springboot集成自动编写API文档

article 2024/11/24 0:14:14

1.第一步先导入所需的依赖

<dependency>
     <groupId>com.github.xiaoymin</groupId>
         <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
     <version>4.3.0</version>
</dependency>

2.第二步编写配置类，title文档标题 version版本 description描述

@Configuration
public class Knife4jConfiguration {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("hello-knife4j项目API")
                        .version("1.0")
                        .description("hello-knife4j项目的接口文档"));
    }
    
    @Bean
    public GroupedOpenApi userAPI() {
        return GroupedOpenApi.builder().group("用户信息管理").
                pathsToMatch("/user/**").
                build();
    }

    @Bean
    public GroupedOpenApi systemAPI() {
        return GroupedOpenApi.builder().group("产品信息管理").
                pathsToMatch("/product/**").
                build();
    }

3.创建一个实体类用作相应请求参数，Schema这个注解标识响应请求参数的描述

@Data
@Schema(description = "用户信息实体")//
public class User {
    @Schema(description = "用户id")
    private Long id;
    @Schema(description = "用户名")
    private String name;
    @Schema(description = "用户年龄")
    private Integer age;
}

4.编写一个controller

@RestController
@RequestMapping("/user")
@Tag(name = "用户信息管理") //标识这个类的作用
public class UserController {

    @GetMapping("getById")
    @Operation(summary = "根据ID查询用户信息") //文档标题
    //@Parameter(description = "用户ID") 请求参数说明
    public User getById(@Parameter(description = "用户ID") @RequestParam("id") Long id){
        User user=new User();
        user.setId(id);
        user.setName("小猪");
        user.setAge(10);
        return user;
    }
}

上面的步骤完成后就可以启动访问这个地址查看文档http://localhost:8080/doc.html，在项目中添加的注解都显示到对应的地方，如果没有添加或者是用错了那API文档就不会显示描述