Support for JEP 413 in OpenAPI Description

[originalrusyn]

Is your feature request related to a problem? Please describe.

I'm consistently challenged when documenting Java APIs using OpenAPI Description (YAML or JSON) due to the absence of native support for JEP 413. This JEP introduces the @snippet Javadoc tag, which significantly enhances the ability to document examples directly within Javadoc comments. Presently, there exists a functional albeit clumsy workaround involving the combination of the @code tag and <pre> and </pre> tags.

Describe the solution you'd like

I propose integrating support for JEP 413 directly into OpenAPI Description, thereby enabling the recognition and proper interpretation of the @snippet tag within Javadoc comments. This enhancement would empower developers to seamlessly embed example descriptions from Javadoc comments into the OpenAPI documentation. Consequently, API documentation would become more comprehensive, illustrative, and maintainable.

The conversion process should maintain the format of the @snippet tag as follows:

from:

     /**
     *
     * {@snippet id='t' lang="JSON" :
     *  {
     *   "a": 1,
     *   "b": 2
     *  }
     * }
     */

to:

{
   "a": 1,
   "b": 2
 }

Instead of converting it to:

{@snippet id='t' lang="JSON" : { "a": 1, "b": 2 } }

Describe alternatives you've considered

The current alternative requires manual formatting of Javadoc comments using a combination of the @code tag and <pre> and </pre> tags. However, this method is laborious, prone to errors, and time-consuming. By directly supporting JEP 413 within OpenAPI Description, the need for such cumbersome workarounds would be eliminated, streamlining the documentation process significantly.