Fixing template to support javadocs generation for arrays and maps - #2010
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the Javadoc template for Jersey3 to conditionally use {@code} for container types (such as lists or maps) and {@link} for standard types across path, body, query parameters, and return types. This prevents Javadoc compilation errors with generic types. The feedback suggests a minor improvement to use the current context reference {{{.}}} instead of {{{returnType}}} inside the returnType block to avoid unnecessary parent context lookups and maintain consistency.
| * @param requestOptions {@link RequestOptions } Object to store additional HTTP headers such as idempotency-keys (optional) | ||
| {{#returnType}} | ||
| * @return {@link {{.}} } | ||
| * @return {{#returnContainer}}{@code {{{returnType}}} }{{/returnContainer}}{{^returnContainer}}{@link {{.}} }{{/returnContainer}} |
There was a problem hiding this comment.
Inside the {{#returnType}} block, the current context (.) is already the returnType string. It is more idiomatic and robust to use {{{.}}} instead of {{{returnType}}} to refer to the current context. This avoids unnecessary parent context lookup and maintains consistency with the fallback {@link {{.}} }.
* @return {{#returnContainer}}{@code {{{.}}} }{{/returnContainer}}{{^returnContainer}}{@link {{.}} }{{/returnContainer}}
|
2 participants
Description
The Javadoc build fails with error:
unexpected text when a generated API method has a parameter or return type that is a generic container (e.g. List<ExecutionResult>).This PR fixes the OpenAPI Mustache template so those types render as valid Javadoc.
The api_summary.mustache template embedded the parameter/return type inside a {@link} tag using double-brace interpolation ({@link {{dataType}} }). Mustache HTML-escapes {{ }}, so a generic type like List was emitted as:
This never surfaced before because the {@link } pattern is only used for operation parameters/return types (model fields use the property name, not the type), and no prior operation had a container-typed parameter or return.
Tested scenarios
Fixed issue:
For container types (isContainer), render the type with {@code} (which safely handles angle brackets and needs no reference resolution) using unescaped triple-brace interpolation.
Non-container types are unchanged and still use clickable {@link}.
• List → {@code List } (valid, renders the full generic type)
• String, Integer, model classes → still {@link ... } (clickable, unchanged)
Applied to path params, body params, query params, and the @return tag.