Swagger-ui: Model of all methods annotated with responseContainer = "List" incorrectly begins with Inline Model [ Inline Model 1 ]

[pgodzin]

This issue comes up for every method annotated with responseContainer = "List"

For instance, we have this getOrgs method and corresponding generated model:

@GET
@Path("/orgs")
@ApiOperation(value = "Lists all Orgs.", response = Org.class, responseContainer = "List", position = 1)
@ApiResponses(value = {@ApiResponse(code = 500, message = Constants.BASE_PATH_NOT_FOUND) })
public List<Org> getOrgs() throws ServiceException;

Inline Model [
    Inline Model 1
]
Inline Model 1 {
    id (string, optional),
    batches (Array[Batch], optional)
}
Batch {
    id (integer, optional),
}

Instead of Inline Model 1, we expect it to say Org, as annotated by the response property. The swagger.json correctly states that the response is a collection of Orgs:

"summary":"Lists all Orgs.","description":"","operationId":"getOrgs","parameters":[],"responses":{"200":{"description":"successful operation","schema":{"type":"array","items":{"$ref":"#/definitions/Org"}}}

Instead, we get the following schema:

Before grabbing last week's dist folder and upgrading to swagger-core and swagger-jaxrs 1.5.9, we were on version 1.3 and the model for getOrgs was:

Org {
     id (string, optional),
     batches (array[Batch], optional)
}
Batch {
    id (integer, optional),
}

All methods returning a single Org are displayed properly with no inline methods. The Org model class has no annotations on it. Is this a known Swagger issue with responseContainer = "List" methods or is there something we are missing that has changed in the new versions of Swagger?

[webron]

No, this looks like an oversight. I agree that in case of top-level arrays, we should try to avoid referring those as inline definitions.

However, given the method signature you provided from Java, I think you may be able to drop the response and responseContainer and you'll get the result you want. By the way position can also be dropped as it's been deprecated.

That is:

@GET
@Path("/orgs")
@ApiOperation(value = "Lists all Orgs.")
@ApiResponses(value = {@ApiResponse(code = 500, message = Constants.BASE_PATH_NOT_FOUND) })
public List<Org> getOrgs() throws ServiceException;

[pgodzin]

Thanks, that helps clean up the annotations.

However, the Inline Model 1 issue persists without those annotation properties. Any other suggestions you can think of?

Looking at the Pet Store sample the annotations were similar with response and responseContainer="List", but findByStatus correctly displays the Pet model:

Inline Model [
    Pet
]
Pet {
    id (integer, optional),
    category (Category, optional),
    name (string),
    photoUrls (Array[string]),
    tags (Array[Tag], optional),
    status (string, optional): pet status in the store = ['available', 'pending', 'sold']
} 

[webron]

What does your operation look like in swagger spec now?

[pgodzin]

Changed the annotations and method signature to the one you specified, the model and the swagger.json remained the same as the one I originally posted.

[webron]

Wait, is the rendering in swagger-ui identical to the original one you shared?

[pgodzin]

Yes, using

    @GET
    @Path("/orgs")
    @ApiOperation(value = "Lists all Orgs.")
    @ApiResponses(value = {@ApiResponse(code = 500, message = Constants.BASE_PATH_NOT_FOUND) })
    public List<Org> getOrgs() throws ServiceException;

still results in

Inline Model [
    Inline Model 1
]
Inline Model 1 {
    id (string, optional),
    batches (Array[Batch], optional)
}
Batch {
    id (integer, optional),
}

Any other suggestions? Where does the UI look for the name to place where Inline Model 1 currently is? It doesn't appear to be the items $ref in the swagger.json since it is properly identified there as Org type.

[pgodzin]

If you look at the swagger-ui dist for every version 2.1.5 and after, the petstore sample found at index.html includes the same problem for findByStatus. So this is a swagger-ui issue

[lafrech]

I think I'm facing the same issue.

In version 2.1.4 and older, I get the correct output:

Inline Model [
Building
]

Building {
city (string, optional),
construction_date (string, optional),
id (string, optional, read only),
name (string),
state (State, optional, read only)
}

State {
area (string, optional),
id (string)
}

From 2.1.5 on, I get

Inline Model [
Inline Model 1
]

Inline Model 1 {
city (string, optional),
construction_date (string, optional),
id (string, optional, read only),
name (string),
state (State, optional, read only)
}

State {
area (string, optional),
id (string)
}

More precisely, git bisect tells me the issue appears in https://github.com/swagger-api/swagger-ui/commit/30ed33c446b69422c371c20e415225e05caea2b2.

This happens for array responses, like this:

        "responses": {
          "200": {
            "description": "", 
            "schema": {
              "items": {
                "$ref": "#/definitions/Building"
              }, 
              "type": "array"
            }
          }
        }, 

not when the API returns a single instance:

        "responses": {
          "201": {
            "description": "", 
            "schema": {
              "$ref": "#/definitions/Building"
            }
          }
        }, 

I hope this helps...

[ericorange]

I am new to working with this project, but it seems like this issue came up when a change was made in swagger-js in swagger-js/pull/746. Reverting the change to lib/resolver.js from that commit and pulling it into swagger-ui fixed this for me in the Pet Store UI, but that would undoubtedly also revert the functionality that was supposedly added with that pull request.

[tonyzakula]

I am also seeing this with and object, even when it is not a list

[dolmen]

@fehguy It looks that @lafrech made a strong analysis of the issue...

[webron]

This is no longer an issue with 3.X.