swagger-api / swagger-api/swagger-codegen

[JAVA] Bug generating ApiModelProperty example parameter for objects and enums

Open
#4,312 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

When generating a Java client, the example parameter in the ApiModelProperty annotation of a POJO is set to null for Java objects and enums regardless of the example value in the swagger file.

Swagger-codegen version

I have tested this on the 2.2.2-SNAPSHOT I built from git and the 2.2.1 release I downloaded from maven.

Swagger declaration file content or url
definitions:
  Person:
    type: object
    properties:
      name:
        type: string
        example: Julie
      sex:
        $ref: '#/definitions/Sex'
      birthdate:
        type: object
        properties:
          date:
            type: string
            example: "12/12/1992"
  Sex:
    type: string
    enum:
      - male
      - female
    example: female
Command line used for generation

java -jar swagger-codegen-cli.jar generate -i swagger.yaml -o swagger-definitionWithExamples -l java -Dmodels=Person,PersonBirthdate,Sex

Steps to reproduce

Run the previous command with the provided swagger definition. Look at the ApiModelProperty of the generated Java code.

grep -r @ApiModelProperty swagger-java-definition/

Suggest a Fix

This issue where the example parameter is set to null does not exist in the Spring code generation because of these lines:

@Override
    public void postProcessModelProperty(CodegenModel model, CodegenProperty property) {
        super.postProcessModelProperty(model, property);

        if ("null".equals(property.example)) {
            property.example = null;
        }
        ...

My proposition is to add the same thing to JavaClientCodegen.java.
I have tested this fix and it works.
But since both classes extend AbstractJavaCodegen, maybe this code could be refactored there.

Also, this fix does not solve the problem where the enum example parameter is not set to the example value in the swagger file.

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 JavaClientCodegen.java and compare its model-property post-processing with the Spring implementation cited in the issue. Run the provided swagger-codegen CLI command against the YAML definition, then inspect the generated ApiModelProperty annotations. Done means object and enum examples from the Swagger definition are retained instead of becoming null or being omitted.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.