ql-link/linkrag-service/swagger-annotation

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.tags.Tag;

@RestController
@RequestMapping("/api/v1/xxx")
@Tag(name = "XXX管理接口", description = "提供XXX的创建、查询、更新、删除功能")
public class XxxController { ... }

@GetMapping("/{id}")
@SaCheckLogin
@Operation(
    summary = "查询XXX详情",
    description = "根据ID查询单条XXX记录，包含完整字段信息"
)
public Result<XxxDTO> getById(@PathVariable Long id) { ... }

@GetMapping
public Result<PageResult<XxxDTO>> list(
    @Parameter(description = "状态筛选，可选值：ACTIVE、INACTIVE", example = "ACTIVE")
    @RequestParam(required = false) String status,
 
    @Parameter(description = "页码，从 1 开始", example = "1")
    @RequestParam(defaultValue = "1") int page,
 
    @Parameter(description = "每页条数", example = "20")
    @RequestParam(defaultValue = "20") int pageSize
) { ... }

@Data
@Schema(description = "XXX信息")
public class XxxDTO {
 
    @Schema(description = "主键ID", example = "10001")
    private Long id;
 
    @Schema(description = "名称", example = "我的XXX")
    private String name;
 
    @Schema(description = "状态：ACTIVE 正常, INACTIVE 已停用", example = "ACTIVE")
    private String status;
 
    @Schema(description = "创建时间")
    private LocalDateTime createdAt;
}

@Schema(description = "任务状态：PENDING 待处理, PROCESSING 处理中, SUCCESS 成功, FAILED 失败", example = "PENDING")
private String status;

# 启动服务
mvn spring-boot:run -pl link-api
# 访问 Knife4j 文档页（端口 8080）
# http://localhost:8080/doc.html