swagger-api / swagger-api/swagger-codegen

[JAVA jersey2] Model property with description, allOf and $ref results in a class with no fields

Open
#10,857 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Mustache
Stars
17.8k
Forks
6k
PR merge metrics
No merged PRs in 30d

Description

Description

Given a model like this:

definitions:
  Resource:
    type: object
    properties:
      address:
        $ref: '#/definitions/ResourceAddress'
      level:
        description: Some description for level.
        allOf:
          - $ref: '#/definitions/TimestampedIntegerValue'

Up to version 2.4.14, it used to generate fields like this:

  @JsonProperty("address")
  private ResourceAddress address = null;

  @JsonProperty("level")
  private Object level = null;

At runtime, the Object level field would contain a Map with the fields from JSON. Not ideal but works.
Starting with version 2.4.15, it now generates fields like this:

  @JsonProperty("address")
  private ResourceAddress address = null;

  @JsonProperty("level")
  private ResourceLevel level = null;

And ResourceLevel is generated as an empty class -- no fields, just equals(), hashCode(), toString() and toIndentedString() methods.

You can find a fully self-contained project attached to this issue: sample-swagger-codegen-allOf-bug-project.zip

Swagger-codegen version

2.4.15+ is broken.
2.4.14 is the last version known to work.

Steps to reproduce, command line used for generation

Unzip the attached project (sample-swagger-codegen-allOf-bug-project.zip) and run

./gradlew clean test jar

With 2.4.15+, the test will fail.
With 2.4.14, the test will pass.

Related issues/PRs

Might be related to:

  • #8002
  • #9720
  • #10446
Suggest a fix/enhancement

At the very least, the new version should not break the old behavior. Although the previous way of getting access to the data via a Map was inconvenient, at least I could get access to the data. With new version, there is no way to get access to the data (and it will actually fail to parse the valid JSON in case I would disable ignoring unknown attributes).

Even better would be to handle the special case where description, allOf and $ref are combined to add a description to otherwise generic model type. With such special case handling, the actual type of level field would be TimestampedIntegerValue and description would become JavaDoc for that field.

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

Unpack the attached sample project and run ./gradlew clean test jar with swagger-codegen 2.4.15+ and 2.4.14 for comparison. Trace the Java Jersey2 model generation path for a property combining description, allOf, and $ref. Done means the generated level field remains usable and the sample project's test passes without regressing the 2.4.14 behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
backend-api-design, tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.