How's one to add hyperlinks and tables in the description?

[Jonathan-Zollinger]

when adding hyperlinks or tables in the openapi description, the html syntax is url encoded such that the strings are simply text. How should one go about adding hyperlinks and tables in descriptions? I assume that's supported, but let me know if this isn't supported.

for instance, this description tag in the openapi file (from zendesk's helpcenter api):

/api/v2/help_center/{locale}/articles/{article_id}:
parameters:
  - $ref: '#/components/parameters/OptionalLocale'
  - $ref: '#/components/parameters/ArticleId'
...
delete:
  operationId: ArchiveArticle
  tags:
    - Articles
  summary: Archive Article
  description: |
    Archives the article. You can restore the article using the Help Center user interface. {@see <a href='https://support.zendesk.com/hc/en-us/articles/235721587'>Viewing and restoring archived articles</a>}.
    Allowed for Agents
  responses:
    "204":
      description: Default success response

turns to this once compiled:

/**
 * {@summary Archive Article}
 * Archives the article. You can restore the article using the Help Center user interface. {@see <a href='https://support.zendesk.com/hc/en-us/articles/235721587'>Viewing and restoring archived articles</a>}.  #### Allowed for  * Agents
 *
 * @param locale The locale the item is displayed in (required)
 * @param articleId The unique ID of the article (required)
 * @return Default success response (status code 204)
 */

I've tried using @see tags as well, I can't seem to get this to avoid being url-encoded. Any help is appreciated!

[altro3]

@Jonathan-Zollinger Fixed it here: #2294

But I told you early - please, don't use discussions, because I forgot about it. Create an issue, if you see, that something is wrong or you have ideas for new features

[altro3]

@Jonathan-Zollinger Also want ot say: by OpenAPI specification, you can't use html code in descriptions, but you can use markdown for it

[Jonathan-Zollinger]

since markdown isn't supported natively in java-docs, what is the supported path with this product?

[altro3]

since markdown isn't supported natively in java-docs, what is the supported path with this product?

Yes, I know. MD will be support in JDK 25. Let me clarify: html will work correctly, the error was in the code, I gave you a link to the fix. With version 6.18.0 everything will work.

I just clarified that in general, this is not correct according to the OpenAPI 3.0 specification.

I think we need to add a setting or auto-detection of the javadoc type - md or html and convert it to the required format - html or md. Immediately for JDK25 support