Javadoc Enhancements

[gebezs]

The Javadoc support can be further enhanced by using it in more places and by providing support for standard Javadoc conventions.

1. The RestDto class javadoc should be set as the description of the Schema.
2. The RestController class javadoc should be set as the description of the Tag.
3. The RestController method javadoc's first sentence should be set as the Operation's summary.
4. The RestController method javadoc's @throws should be used to override the generic description
5. 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.

All the quotes are from the Oracle Javadoc page.

[gebezs]

I created a PR: #1579
Once you are happy with that I'll update the old tests and I'll open another one PR to update the documentation.

[bnasslahsen]

@gebezs,

Please feel free to proceed and update the tests.
Once you are done, just le met know so we can proceed with the merge!

[gebezs]

@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.

[bnasslahsen]

Fixed by #1579