In a nested swagger ApiModel, the inner ApiModel's ApiModelProperty 'example' isn't showed on the swagger definition

Hi,

I’m having an ApiModel which contains another ApiModel (nested). In the swagger definition file, generated for my web app, doesn’t have the annotated property, ‘example’, for the attributes that are there in the nested ApiModel (inner ApiModel). But annotated example values for the attributes in the outer ApiModel is there in the swagger definition.

Let me further explain this with an example. (I will explain what I meant by inner ApiModel and outer ApiModel through the following example)

My “ListActivity” class is annotated with “@ApiModel” annotation as below. This is the outer ApiModel

@ApiModel(
            value = "List of activities", 
            description = "This contains a set of activities that matches a given criteria as a collection")
public class ActivityList

Inside the “ActivityList” class I have two attributes. Those are integer -> “count” and List<Activity> -> “activities”. Both these attributes are annotated using “@ApiModelProperty” annotation as below.

@ApiModelProperty(
            value = "Number of total resources.",
            example = "1")
 @JsonProperty("count")
 private int count;

@ApiModelProperty(
            value = "Returns the list of activities that match the offset and limit parameter values that were specified.")
@JsonProperty("activities")
private List<Activity> activities;

Since “Activity” is an object, I created an ApiModel for the “Activity” class. I’m annotating it as below.

Now this is the inner ApiModel which is inside the “ActivityList” ApiModel (outer ApiModel). (Hope now you can understand what I meant by nested ApiModels).

@ApiModel(
          value = "Activity", 
         description = "An activity instance carries a unique identifier that can be used to identify a particular operation instance uniquely")
public class Activity;

Inside “Activity” class, I have another two attributes. Those are String -> “activityId” and String -> “code”. I’m annotating those attributes using @ApiModelProperty as shown below.

@ApiModelProperty(
            name = "activityId",
            value = "Activity identifier",
            required = true,
            example = "ACTIVITY_1")
@JsonProperty("activityId")
private String activityId;

@ApiModelProperty(
            name = "code",
            value = "Activity code",
            required = true,
            example = "DEVICE_RING")
@JsonProperty("code")
private String code;

After that I’m generating the swagger definition file. In the generated file, example values were set only to the attribute “count” which was in the outer ApiModel. That means the “count” attribute’s example value is set to “1” as I annotated in the above given example.

But all the example values that I set in inner ApiModel which are the attributes of “Activity” class, does not come to the generated swagger definition file. Instead it only shows “type”: “string”. As per the example given above, example values, “ACTIVITY_1” and “DEVICE_RING” isn’t set in the swagger definition file, for “activityId” and “code” attributes.

Therefore on the swagger UI, the json schema that I’m getting is as shown below. Only “count” is set to “1” and other keys are set with their data types.

{
    "count": 1,
    "activities": [{
        "activityId": "string",
        "code": "string"
    }]
}

The swagger definition is as below.

 "List of activities": {
         "type": "object",
         "properties": {
            "count": {
               "type": "integer",
               "format": "int32",
               "example": 1, **(example values are set here as given in the annotations)** 
               "description": "Number of total resources."
            },

            "activities": {
               "type": "array",
               "description": "Returns the list of activities that match the offset and limit parameter values that were specified.",
               "items": {
                  "$ref": "#/definitions/Activity"
               }
            }
         },
         "description": "This contains a set of activities that matches a given criteria as a collection"
}


"Activity": {
         "type": "object",
         "properties": {
            "activityId": {
               "type": "string" **(example values are not set here though I set it in the annotations, even the property 'example' isn't displayed)**  
            }
         }
 }

Therefore, in a nested swagger ApiModel, the inner ApiModel’s ApiModelProperty ‘example’ isn’t showed on the swagger definition.

Is there anyway that I can set this example property to the inner ApiModel’s attributes when generating the swagger definition?

Thank you

[akrestan]

Hi,

what is the status of this issue? It’s not clear why it has been closed. I am experiencing a situation that looks similar to what is described above in Java when nested objects, whose classes are annotated with @ApiModel, are not generated in swagger JSON client API definition. It makes no difference if the Java classes of the nested objects are placed in their own compilation unit are declared as nested classes of the API argument class for which the JSON is generated.

Thanks for letting me know

[webron]

It’s a closed issue from 2016. A lot has changed since then. If you still experience a problem, it’s better to file a new detailed ticket.