[Feature-Request] Derive documentation from javadoc

[ST-DDT]

This is a feature request.

IMO writing the documentation via annotations is tedious. I would rather write javadocs and let the plugin convert them into proper documentation.

Can you add support for that?

If annotations are present and the description part is filled, then it should use that description. If the annotation is missing or the description is empty, then it should use the javadocs instead.

A helpful library for the implementation might be https://github.com/dnault/therapi-runtime-javadoc

Hi,

We are not focusing to use javadoc to generate the OpenAPI Description.
We rely on the swagger annotations to generate the API documentation.
This feature, might be planned on a future release.

[Quantumplation]

Would you be willing to reconsider this feature request now that some time has passed? The annotations approach is particularly more verbose, and pulling descriptions from the javadocs would be significantly more ergonomic.

[ghilainm]

Any play to reopen this issue? Seems super convenient at first sight (and quite natural from a user perspective as a good default).

[matthewadams]

Ditto ⬆️

[bnasslahsen]

The support will be added with version: 1.5.11.

For a project that wants to enable javadoc support, you should add the following dependency, together with the springdoc-openapi-ui dependency:

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

This dependency improves the support of javadoc tags and comments:

• The javadoc comment of a method: is resolved as the @Operation description
• @return : is resolved as the @Operation response description
• The javadoc comment of a parameter in a method, will be resolved as @Parameter or @RequestBody description
• The javadoc comment of an attribute: is resolved as @Schema description for this field.

This dependency is based on the library https://github.com/dnault/therapi-runtime-javadoc[therapi-runtime-javadoc]
If both a swagger-annotation description and a javadoc comment are present. The value of the swagger-annotation description will be used.

NOTE: Make sure, you enable the annotation processor of therapi-runtime-javadoc in order to enable javadoc support for springdoc-openapi.

<build>
	<plugins>
		<plugin>
			<groupId>org.apache.maven.plugins</groupId>
			<artifactId>maven-compiler-plugin</artifactId>
			<configuration>
				<annotationProcessorPaths>
					<path>
						<groupId>com.github.therapi</groupId>
						<artifactId>therapi-runtime-javadoc-scribe</artifactId>
						<version>0.12.0</version>
					</path>
				</annotationProcessorPaths>
			</configuration>
		</plugin>
	</plugins>
</build>