1

First of all, the following repository has all the code (and description as well) to reproduce this problem: https://github.com/elgleidson/swagger-problem

I have the following JSON:

{
  "nonNullableField": "not null",
  "nullableField": null,
  "nonNullableObjectField": {
    "someField": "some value"
  },
  "nullableObjectField": null,
  "nonNullableList": [
    "not null"
  ],
  "nullableList": null,
  "nonNullableObjectList": [
    {
      "someField": "some value"
    }
  ],
  "nullableObjectList": null
}

Which is mapped to the following Java classes:

@Value
public class MyResponse {

  @Schema(nullable = false, description = "DO NOT map to json object and DO NOT allow null")
  private final String nonNullableField = "not null";

  @Schema(nullable = true, description = "DO NOT map to json object and allows null")
  private final String nullableField = null;

  @Schema(nullable = false, description = "map to json object and DOES NOT allow null")
  private final MyClass nonNullableObjectField = new MyClass(nonNullableField);

  @Schema(nullable = true, description = "map to json object and allows null")
  private final MyClass nullableObjectField = null;

  @ArraySchema(arraySchema = @Schema(nullable = false, description = "list that DOES NOT map to json object and DOES NOT allow null"))
  private final List<String> nonNullableList = List.of(nonNullableField);

  @ArraySchema(arraySchema = @Schema(nullable = true, description = "list that DOES NOT map to json object and allow null"))
  private final List<String> nullableList = null;

  @ArraySchema(arraySchema = @Schema(nullable = false, description = "list that map to json object and DOES NOT allow null"))
  private final List<MyClass> nonNullableObjectList = List.of(nonNullableObjectField);

  @ArraySchema(arraySchema = @Schema(nullable = true, description = "list that map to json object and allow null"))
  private final List<MyClass> nullableObjectList = null;

}

@Value
@Schema(description = "my class description")
public class MyClass {

  @Schema(description = "my class field description")
  private final String someField;

}

When I go to /v3/api-docs (or /swagger-ui.html) the following documentation is generated:

{
  "MainResponse": {
    "type": "object",
    "properties": {
      "nonNullableField": {
        "type": "string",
        "description": "DO NOT map to json object and DO NOT allow null"
      },
      "nullableField": {
        "type": "string",
        "description": "DO NOT map to json object and allows null",
        "nullable": true
      },
      "nonNullableObjectField": {
        "$ref": "#/components/schemas/MyClass"
      },
      "nullableObjectField": {
        "$ref": "#/components/schemas/MyClass"
      },
      "nonNullableList": {
        "type": "array",
        "description": "list that DOES NOT map to json object and DOES NOT allow null",
        "items": {
          "type": "string"
        } 
      },
      "nullableList": {
        "type": "array",
        "description": "list that DOES NOT map to json object and allow null",
        "nullable": true,
        "items": {
          "type": "string"
        }
      },
      "nonNullableObjectList": {
        "type": "array",
        "description": "list that map to json object and DOES NOT allow null",
        "items": {
          "$ref": "#/components/schemas/MyClass"
        }
      },
      "nullableObjectList": {
        "type": "array",
        "description": "list that map to json object and allow null",
        "nullable": true,
        "items": {
          "$ref": "#/components/schemas/MyClass"
        }
      }
    }
  },
  "MyClass": {
    "type": "object",
    "properties": {
      "someField": {
        "type": "string",
        "description": "my class field description"
      }
    },
    "description": "my class description",
    "nullable": true
  }
}

As you can see, for the fields whose types are not mapped to object the documentation is generated as expected. The same doesn't happen for nullableObjectField: the nullable property is put in MyClass definition instead of the field.

I would like to generate the following documentation instead:

{
  "MainResponse": {
    "type": "object",
    "properties": {
      "nonNullableField": {
        "type": "string",
        "description": "DO NOT map to json object and DO NOT allow null"
      },
      "nullableField": {
        "type": "string",
        "description": "DO NOT map to json object and allows null",
        "nullable": true
      },
      "nonNullableObjectField": {
        "$ref": "#/components/schemas/MyClass",
        "description": "map to json object and DOES NOT allow null"
      },
      "nullableObjectField": {
        "$ref": "#/components/schemas/MyClass",
        "description": "map to json object and allows null",
        "nullable": true
      },
      "nonNullableList": {
        "type": "array",
        "description": "list that DOES NOT map to json object and DOES NOT allow null",
        "items": {
          "type": "string"
        } 
      },
      "nullableList": {
        "type": "array",
        "description": "list that DOES NOT map to json object and allow null",
        "nullable": true,
        "items": {
          "type": "string"
        }
      },
      "nonNullableObjectList": {
        "type": "array",
        "description": "list that map to json object and DOES NOT allow null",
        "items": {
          "$ref": "#/components/schemas/MyClass"
        }
      },
      "nullableObjectList": {
        "type": "array",
        "description": "list that map to json object and allow null",
        "nullable": true,
        "items": {
          "$ref": "#/components/schemas/MyClass"
        }
      }      
    }
  },
  "MyClass": {
    "type": "object",
    "properties": {
      "someField": {
        "type": "string",
        "description": "my class field description"
      }
    },
    "description": "my class description"
  }
}

How can I do that? Is it possible?

2
  • 1
    It seems like a swagger-core bug, so I have opened a issue on their project: github.com/swagger-api/swagger-core/issues/3518 Commented Apr 17, 2020 at 8:45
  • i think, this question should be flagged as answered then ? Commented Dec 1, 2020 at 21:25

1 Answer 1

0

It looks like its a swagger bug:

Sign up to request clarification or add additional context in comments.

Comments

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.