接入

引入依賴

引用 Knife4j 的 starter

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

修改配置

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.ftl.xtrack
# knife4j的增強配置，不需要增強可以不配
knife4j:
  enable: false
  setting:
    language: zh_cn

使用示例

接口示例

@RestController
@Tag(name = "用戶 API", description = "用戶相關接口")
public class UserController {

    @Operation(summary = "普通body請求", description = "普通body請求")
    @PostMapping("/body")
    public ResponseEntity<User> body(@RequestBody User user) {
        return ResponseEntity.ok(user);
    }

    @Operation(summary = "普通body請求+Param+Header+Path")
    @Parameters({
            @Parameter(name = "id", description = "文件id", in = ParameterIn.PATH),
            @Parameter(name = "token", description = "請求token", required = true, in = ParameterIn.HEADER),
            @Parameter(name = "name", description = "文件名稱", required = true, in = ParameterIn.QUERY)
    })
    @PostMapping("/bodyParamHeaderPath/{id}")
    public ResponseEntity<User> bodyParamHeaderPath(
            @PathVariable("id") String id,
            @RequestHeader("token") String token,
            @RequestParam("name") String name,
            @RequestBody User user) {
        user.setName(user.getName() + ",receiveName:" + name + ",token:" + token + ",pathID:" + id);
        return ResponseEntity.ok(user);
    }
}

實體示例

@Getter
@Setter
@Schema(name = "User ", description = "用戶信息實體")
public class User {
	@Schema(description = "姓名", requiredMode = Schema.RequiredMode.REQUIRED, example = "張三" )
    private String name;

    @Schema(description = "年齡", requiredMode = Schema.RequiredMode.AUTO, example = "20")
    private Integer age;

    @Schema(description = "年齡", requiredMode = Schema.RequiredMode.NOT_REQUIRED, hidden = true)
    private LocalDateTime createdAt;
}