OpenAPITools / OpenAPITools/openapi-generator

Java generator: parameter defaultValue not escaped in @param Javadoc, breaks compilation for values containing "*/"

Open Beginner friendly
#24,852 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Java
Stars
26.8k
Forks
7.7k
PR merge metrics
PR metrics pending

Description

Description

When a parameter's OpenAPI schema has a default value containing the
sequence */ (e.g. an Accept header defaulting to */*), the generated
Java client's @param Javadoc line embeds that value raw and unescaped,
which prematurely closes the enclosing /** ... */ comment block and
produces a Java file that fails to compile.

openapi-generator version

7.25.0 (also reproduces on other recent versions - the relevant template
code is unchanged on master as of this writing)

Java (client) generator

Steps to reproduce

  1. Minimal OpenAPI 3.1 spec with a header parameter defaulting to */*:

```yaml
openapi: 3.1.0
info:
title: repro
version: "1.0"
paths:
/ping:
get:
operationId: ping
parameters:
- name: Accept
in: header
required: false
schema:
type: string
default: "/"
examples: ["application/json", "text/plain", "/"]
responses:
"200":
description: ok
```

  1. Generate:
    ```
    docker run --rm -v $(pwd):/spec -v /tmp/out:/output
    openapitools/openapi-generator-cli:v7.25.0 generate
    --input-spec /spec/repro.yaml --generator-name java --output /output
    ```

  2. Compile the generated client (e.g. mvn compile).

Actual behavior

Compilation fails. The generated @param line reads:
```

  • @param accept (optional, default to /)
    ```
    The */ inside that text closes the Javadoc block early, so every line
    after it in the same comment becomes invalid Java source.

Expected behavior

The generated client should compile. defaultValue (and any other
free-text value interpolated into a Javadoc comment) should go through
comment-safe escaping, the same way consumes/produces content types
are handled via escapeText() in addConsumesInfo (see #10598, which
is the same underlying class of bug in the other direction).

Related

  • Reported downstream as apache/airflow#72466
  • The relevant template: Java/libraries/okhttp-gson/api.mustache,
    the {{#defaultValue}}, default to {{.}}{{/defaultValue}} line -
    {{.}} only gets Mustache's HTML-entity escaping, not Java-comment
    escaping.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with Java/libraries/okhttp-gson/api.mustache and the {{defaultValue}} interpolation described in the issue. Compare it with the escapeText() handling in addConsumesInfo, then regenerate the minimal OpenAPI specification and run mvn compile; done means a default containing */ no longer breaks the generated Javadoc or compilation.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api, tooling
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.