You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The Javadoc support can be further enhanced by using it in more places and by providing support for standard Javadoc conventions.
The RestDto class javadoc should be set as the description of the Schema.
The RestController class javadoc should be set as the description of the Tag.
The RestController method javadoc's first sentence should be set as the Operation's summary.
The RestController method javadoc's @throws should be used to override the generic description
Only the declared exceptions should be used as generic response. (This is a prerequisite for no. 4.)
The 1. and 2. is self explanatory.
The 3. is a standard convention of the javadoc: the first sentence is used in the overview tables and the whole javadoc comment in the detailed part:
Write the first sentence as a short summary of the method, as Javadoc automatically places it in the method summary table (and index).
The 4. is also a standard convention:
A @throws tag should be included for any checked exceptions (declared in the throws clause), as illustrated below, and also for any unchecked exceptions that the caller might reasonably want to catch, with the exception of NullPointerException. Errors should not be documented as they are unpredictable.
The 5. is simply required as in case of 4. only the declared exceptions should be used for the API Response not all of them.
The 4. and 5. should be disabled by default as otherwise it would break backward compatibility.
This solution would allow a bit more control over the generated OpenAPI for developers who would like to use Javadoc only.
@bnasslahsen
I finished the PR, please let me know if you need any changes.
I won't have access to my computer for about a week but after that I'll continue with updating the documentation.
The Javadoc support can be further enhanced by using it in more places and by providing support for standard Javadoc conventions.
@throws
should be used to override the generic descriptionThe 1. and 2. is self explanatory.
The 3. is a standard convention of the javadoc: the first sentence is used in the overview tables and the whole javadoc comment in the detailed part:
The 4. is also a standard convention:
The 5. is simply required as in case of 4. only the declared exceptions should be used for the API Response not all of them.
The 4. and 5. should be disabled by default as otherwise it would break backward compatibility.
This solution would allow a bit more control over the generated OpenAPI for developers who would like to use Javadoc only.
All the quotes are from the Oracle Javadoc page.
The text was updated successfully, but these errors were encountered: