SpringBoot文档

# SpringBoot文档

注解	标注位置	作用
@Tag	controller 类	描述 controller 作用
@Parameter	参数	标识参数作用
@Parameters	参数	参数多重说明
@Schema	model 层的 JavaBean	描述模型作用及每个属性
@Operation	方法	描述方法作用
@ApiResponse	方法	描述响应状态码等

# 案例

pom.xml

 <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
</dependency>

1
2
3
4
5
6
7
8
9
10
11
12
13
14

application.ym配置文件

server:
  port: 8081
# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.joe.controller
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

UserDto


@Schema(description="用户提交数据")
@Data
public class UserDto {

    @Schema(description="用户ID")
    private Integer id;

    @Schema(description="用户名称")
    private String name;

    @Schema(description="用户年龄")
    private Integer age;

    @Schema(description="用户邮箱")

    private String email;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

UserController

@Tag(name="用户管理")
@RestController
public class UserController {

    @Operation(summary = "用户新增")
    @PostMapping("/user")
    public Object add(@RequestBody @Valid UserDto userDto){
        System.out.println("进行保存操作。。。");
        return "";

    }


    @Operation(summary = "用户删除")
    @Parameters({
            @Parameter(name = "id",description = "用户id",in = ParameterIn.PATH),
    })
    @DeleteMapping("/user/{id}")
    public Object delete(@PathVariable Long id){

        return "";
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

访问 http://localhost:8081/doc.html

Last Updated: 2025/12/02, 11:22:00

← SpringBoot事务 SpringBoot Starter和BOM区别→