SpringDoc OpenAPI 中注解继承问题的解决方案

问题背景

在使用SpringDoc OpenAPI为Spring Boot应用生成API文档时，开发者经常需要为大量重复出现的参数或字段添加相同的文档描述。为了避免代码重复，通常会创建自定义注解来封装这些文档元数据。

两种注解方式的对比

参数注解的成功案例

对于方法参数，开发者可以创建一个自定义注解@PersonIdParam，该注解上添加了@Parameter注解：

@Retention(RetentionPolicy.RUNTIME)
@Parameter(description = "Person identifier", example = "1234")
public @interface PersonIdParam {
}

这种方式在控制器方法参数上使用时能够正常工作：

@GetMapping("/person/{id}")
public Mono<PersonDto> getById(@PathVariable @PersonIdParam String id) {
    // ...
}

字段注解的失效问题

当尝试为DTO字段创建类似的注解时，却发现文档元数据没有被正确识别：

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Schema(description = "Person identifier", example = "1234")
public @interface PersonIdField {
}

在DTO中使用时：

public class PersonDto {
    @PersonIdField
    private String id;
    // ...
}

这种情况下，description和example属性不会出现在生成的OpenAPI文档中。

问题根源分析

这个问题的根本原因在于Swagger Core库处理注解的方式。对于字段级别的注解，Swagger Core需要额外的信息来确定如何处理嵌套的注解元数据。

解决方案

通过在自定义注解上添加@JacksonAnnotationsInside注解，可以解决这个问题：

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Schema(description = "Person identifier", example = "1234")
@JacksonAnnotationsInside
public @interface PersonIdField {
}

@JacksonAnnotationsInside注解的作用是告诉Jackson处理器，这个自定义注解内部包含了其他需要处理的注解。这样Swagger Core就能正确识别嵌套在自定义注解中的@Schema注解。

技术原理

1. 注解处理机制：Java注解处理器需要明确知道哪些注解需要被处理，以及如何处理嵌套的注解结构。

2. Jackson的特殊要求：当注解应用于字段时，Jackson需要明确的指示来处理嵌套的注解元数据。

3. Swagger Core的集成：Swagger Core与Jackson紧密集成，遵循Jackson的注解处理规则。

最佳实践建议

1. 对于参数级别的文档注解，直接使用@Parameter即可。

2. 对于字段级别的文档注解，必须添加@JacksonAnnotationsInside才能使嵌套的@Schema生效。

3. 考虑创建统一的文档注解库，集中管理所有API元素的文档描述。

4. 在团队内部建立注解使用规范，确保文档生成的一致性。

总结

通过理解Swagger Core和Jackson的注解处理机制，开发者可以更有效地创建可重用的文档注解。记住字段级注解需要@JacksonAnnotationsInside的特殊要求，可以帮助避免文档生成中的常见问题，提高API文档的质量和一致性。