Search code examples
javaopenapijavadocspringdoc

SpringDoc / OpenAPI: How do deal with JavaDoc vs. @Schema?

I'm working on a Spring Boot project which uses SpringDoc to generate an OpenAPI schema.

I'm struggling with the documentation because on the one hand this:

/** Description of the class */
public class MyClass { ... }

... will be interpreted by the IDE (IntelliJ) as a doc comment, but the Java compiler doesn't preserve it, so it's gone at runtime so SpringDoc cannot read it. On the other hand, this:

@Schema(description = "Description of the class")
public class MyClass { }

... will be interpreted by SpringDoc, but the IDE will not recognize it as a doc comment.

Duplicating the descriptions and having both clearly is also not ideal.

How does everybody else handle this issue?

Solution

  • You can use 'org.springdoc:springdoc-openapi-javadoc', refer to the documentation https://springdoc.org/v1/#javadoc-support. @Schema has a higher priority than javadoc, and the two can be used together.