如何在Spring Boot中标记尚未实现的REST API？

这里有几个实用方案，能让未实现的API在Swagger文档里清晰标识，同时给QA明确提示：

1. 利用@Operation注解添加明确标记 #

直接在接口方法上通过@Operation的描述字段标注未实现状态，还能配合extensions添加自定义标识，让Swagger界面更醒目：

@GetMapping("/unimplemented-api")
@Operation(
    summary = "待实现的用户查询接口",
    description = "⚠️ 此API尚未实现，请勿测试",
    extensions = {
        @Extension(
            name = "status",
            properties = @ExtensionProperty(name = "implementation-status", value = "UNIMPLEMENTED")
        )
    }
)
public ResponseEntity<String> unimplementedApi() {
    return ResponseEntity.status(HttpStatus.NOT_IMPLEMENTED).body("API尚未实现");
}

这样在Swagger UI里，接口描述会直接显示警告信息，extensions里的自定义属性也能在接口详情里看到，同时接口返回501状态码，给调用方明确反馈。

2. 统一返回未实现状态码+分组管理 #

如果有一批未实现的API，可以给它们统一加上路径前缀，然后用@Tag归为单独分组，方法里固定返回HttpStatus.NOT_IMPLEMENTED：

@RestController
@RequestMapping("/unimplemented")
@Tag(name = "未实现API组", description = "此分组下所有API均未完成开发")
public class UnimplementedApiController {

    @GetMapping("/user/list")
    public ResponseEntity<String> userList() {
        return ResponseEntity.status(HttpStatus.NOT_IMPLEMENTED).build();
    }
}

Swagger UI里会单独显示这个分组，QA一眼就能区分哪些是待实现的接口。

3. 自定义注解+SpringDoc扩展 #

如果需要更规范的标记，可以自定义一个@Unimplemented注解，再编写SpringDoc的自定义处理器，自动给带注解的API添加标记：

// 自定义注解
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Unimplemented {
    String reason() default "尚未实现";
}

// SpringDoc扩展处理器
@Component
public class UnimplementedApiProcessor implements OperationCustomizer {
    @Override
    public Operation customize(Operation operation, HandlerMethod handlerMethod) {
        Unimplemented annotation = handlerMethod.getMethodAnnotation(Unimplemented.class);
        if (annotation != null) {
            operation.setDescription("⚠️ " + annotation.reason());
            operation.addExtension("implementation-status", new StringOpenApiExtension("UNIMPLEMENTED"));
        }
        return operation;
    }
}

之后在未实现的接口上直接加@Unimplemented即可，Swagger文档会自动带上标记，不用重复编写描述。

内容的提问来源于stack exchange，提问作者neo007