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

Question

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?

peacetrue · Accepted Answer · 2023-11-23 03:32:13Z

1

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.

answered Nov 23, 2023 at 3:32

peacetrue

3192 silver badges18 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

Martin Häusler Over a year ago

Cool! In case anybody needs it, there's a variation that works for kotlin as well: stackoverflow.com/a/72773537/3094906

fy_kenny · Accepted Answer · 2024-10-17 06:29:34Z

0

https://springdoc.org/#javadoc-support

/** 
 * Summary of the class
 * <p>Description of the class</p>
 */
public class MyClass {
  /** 
 * Summary of the class
 * <p>Description of the class</p>
 * @param req This is parameter summary
 * @return return a Resp object
   */
  public Resp get(Req req) {
    return new Resp()
  }
}

answered Oct 17, 2024 at 6:29

fy_kenny

113 bronze badges

1 Comment

Yunnosch Over a year ago

You might experience unwanted feedback on this for a) link-only to explanation b) otherwise code-only c) (linked) contribution identical to existing answer d) lack of explanation (kind of double with previous, admitted, but to be very explicit on this) This is a pity, because the additional angle to provide a code example I do appreciate. Please consider to edit and stress the angle of more visual explanation, but with explanation.

Collectives™ on Stack Overflow

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

2 Answers 2

1 Comment

1 Comment

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

1 Comment

1 Comment

Your Answer

Sign up or log in

Post as a guest

Linked

Related