SpringDoc/OpenAPI：如何处理JavaDoc与@Schema的文档兼容问题？

在Spring Boot项目中结合SpringDoc生成OpenAPI文档时，无需重复编写JavaDoc和@Schema描述，业内常用以下几种方案：

方案1：启用SpringDoc原生JavaDoc解析 #

SpringDoc自带读取JavaDoc注释生成OpenAPI文档的能力，只需简单配置即可实现“一次编写，两端生效”：

1. 开启JavaDoc解析配置
   在application.properties（或application.yml）中添加：

# 解析实体类属性的JavaDoc作为Schema描述
springdoc.api-docs.resolve-schema-properties=true
# 解析请求体的JavaDoc
springdoc.api-docs.resolve-request-body=true
# 解析响应体的JavaDoc
springdoc.api-docs.resolve-response-body=true

2. 确保构建工具保留JavaDoc可访问性

• Maven项目：在pom.xml中配置maven-javadoc-plugin，确保JavaDoc能被SpringDoc读取：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.5.0</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
</plugin>

• Gradle项目：在build.gradle中启用Javadoc任务：

javadoc {
    options.addStringOption('Xdoclint:none', '-quiet')
}
tasks.withType(Javadoc).all { enabled = true }

配置完成后，只需编写标准JavaDoc注释，IDE会识别为文档，SpringDoc也会自动将其作为OpenAPI Schema的描述。

方案2：用注解处理器自动生成@Schema注解 #

如果需要更精细化的控制，可使用SpringDoc官方提供的注解处理器，在编译阶段自动将JavaDoc内容注入到@Schema的description参数中：

在Maven项目的pom.xml中添加依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-javadoc</artifactId>
    <version>1.6.14</version>
</dependency>

该插件会扫描源码中的JavaDoc注释，自动为实体类、字段生成对应的@Schema注解，你只需维护JavaDoc即可，同时满足IDE识别和SpringDoc的文档生成需求。

方案3：自定义Schema解析逻辑（适合定制化需求） #

如果上述方案无法满足项目的特殊要求，可以通过扩展SpringDoc的Schema生成逻辑，让它优先读取JavaDoc注释，再回退到@Schema的配置：

创建自定义的Schema构建插件：

@Component
public class JavaDocSchemaResolver implements SchemaBuilderPlugin {

    @Override
    public void apply(SchemaGeneratorContext context) {
        AnnotatedType annotatedType = context.getAnnotatedType();
        Class<?> clazz = annotatedType.getType().getErasedType();
        
        // 读取类的JavaDoc并设置为Schema描述
        String classDoc = getClassJavaDoc(clazz);
        if (StringUtils.isNotBlank(classDoc)) {
            context.getSchema().description(classDoc);
        }
        
        // 读取字段的JavaDoc并设置为属性描述
        for (Field field : clazz.getDeclaredFields()) {
            String fieldDoc = getFieldJavaDoc(field);
            if (StringUtils.isNotBlank(fieldDoc) && context.getSchema().getProperties() != null) {
                Schema<?> fieldSchema = context.getSchema().getProperties().get(field.getName());
                if (fieldSchema != null) {
                    fieldSchema.description(fieldDoc);
                }
            }
        }
    }

    // 实现读取类JavaDoc的工具方法（可借助javaparser等库）
    private String getClassJavaDoc(Class<?> clazz) {
        // 示例实现（需引入javaparser依赖）
        // JavaParser parser = new JavaParser();
        // CompilationUnit cu = parser.parse(clazz.getResourceAsStream("/" + clazz.getName().replace(".", "/") + ".java")).getResult().get();
        // return cu.getType(0).getJavadoc().map(Javadoc::getDescription).orElse("");
        return "";
    }

    // 实现读取字段JavaDoc的工具方法
    private String getFieldJavaDoc(Field field) {
        // 类似类的JavaDoc读取逻辑，略
        return "";
    }

    @Override
    public boolean supports(AnnotatedType type) {
        // 适配所有类型，可根据需求调整
        return true;
    }
}

这种方式灵活性最高，但需要自行维护JavaDoc读取的逻辑，适合有定制化文档生成需求的项目。

内容的提问来源于stack exchange，提问作者Martin Häusler