Swagger-core: Resources with same path but different Consumes/Produces are lost

Created on 27 Mar 2015 · 19Comments · Source: swagger-api/swagger-core

We've got a similar scenario as a previously closed bug #521 (2 Resource types differing by @Consumes/@Produces only being lost in swagger spec generation). The bug was closed due to no response, but we've now got the same issue, and the suggested work around by adding @Api('/newPath') no longer works in swagger-jaxrs-1.5.3-M1.

Our scenario is slightly different. We're using @Produces to distinguish between handling a resource as completely different types. For example we would have one resource handler that does GET('image/jpeg'): /file/myImage.png, and returns a jpeg, but we'd have another handler at the same path that does GET('application/json'): /file/myImage.png and returns a json object with essentially meta data that describes what that image means in our system. Further more we would have another GET('application/octet-stream'): /file/myImage.png that would return the raw file, which may not be the same and the return jpeg before (query params could add filters for example). So that's 3 resources with the same path but should be treated completely different.

I agree with the previous bug that the api documentation shouldn't necessarily mimic the actual implementation, but I would've preferred to have them at the same path and have different subsections for each resource endpoint cause they definitely could have different parameters and outputs.

With the current version ('swagger-jaxrs-1.5.3-M1') the swagger reader only takes the resource's
@Path parameters into consideration. So now we're forced to have the docs tied directly to our jersey implementation rather than being able to set @Api value (not used) or override the @ApiOperation base path (since it's been deprecated, not used).

Ultimately we'd prefer to have subsections for each resource path, but using a different doc path is ok too as long as we can set the url separately so the url of the doc resource points to the proper location of the implemented resource.
Has anyone got any suggestions for workarounds? Thanks.

Source

chrisregnier

Most helpful comment

Just a clarification that just as @fehguy said, we are annotating different methods with the same path + http operation but different produces values? If swagger spec does not support this, I think it is a spec bug.

ralf0131 on 17 Nov 2015

👍2

All 19 comments

This is an issue with the Swagger specification as it doesn't allow you to describe overloaded operations that return a different result based on the mime type. This is discussed in https://github.com/swagger-api/swagger-spec/issues/146.

Since it can't be described by the spec, swagger-core cannot support this use case.

webron on 28 Mar 2015

👍1

I understand the spec doesn't work for that scenario, but as I said I'm open to putting things on different documentation paths, and older versions were capable of doing this, however the newest version doesn't take the @Api value into account, or the basePath (which I know has been deprecated). I'd say this is at least a bug in the jersey/jaxrs code. Otherwise, there's a direct 1:1 mapping with the @Path mappings, which means you can't control the docs nearly as well now. So I think the Api value (or basePath) should be used as an override if actually set, since it's more explicit than taking the assumed value from @Path.

chrisregnier on 28 Mar 2015

The value of the @Api affected where the documentation was hosted, not the documentation itself. There's just no way have it documented in Swagger 2.0 and as such there can't be a workaround to it here.

webron on 28 Mar 2015

Just switched to Swagger 1.5M2 and half my documentation disappeared because of this. How is it possible this was missed in the Swagger 2.0 spec? For example, I have a resource to which you can POST JSON, a file in MULTIPART_FORM_DATA, or a raw file in APPLICATION_OCTET_STREAM. So now, not only can't I use Swagger Annotations to document my API, I apparently can't even use Swagger 2.0. Can someone please explain the rationale here, because it escapes me?

BigSocial on 25 Apr 2015

@BigSocial - I've replied to your comment on the _other_ thread.

webron on 26 Apr 2015

@BigSocial perhaps you're bringing up something different. Are you annotating different methods with the same path + http operation but different produces or consumes values? If so that's a bug.

fehguy on 27 Apr 2015

👍2

I think this is a bug too. It should be perfectly legal to have two operations

/pet/{id} which produces application/json implemented by a getPet()
/pet/{id} which produces application/pdf implemented by a getPetDocument()

And instead of producing two different Path.gets in the new terminology, it should collapse the two into one operation with produces = [ 'application/json', 'application/pdf' ]. Its a totally different matter altogether what the resulting operationId should be :)

For sure in springfox I'll be creating a bug to fix that.

dilipkrish on 27 Apr 2015

@dilipkrish See and comment on this thread https://github.com/swagger-api/swagger-spec/issues/146

BigSocial on 27 Apr 2015

@BigSocial which comment in particular? I'm not a fan of having the service description regress into RPCish style describing methods, because thats not what swagger is for.

Couple of things,

I dont believe this is a bug with the spec.
Like @fehguy suggested I think this is just a bug with the swagger-core and its ilk including springfox's implementation of how we scan for an infer operations.

dilipkrish on 27 Apr 2015

@dilipkrish - two different issues. Two methods with different consumes/produces should indeed collapse into one definition. However, you cannot describe a different output based on the mime type (that's what not supported by the spec).

webron on 28 Apr 2015

About the second case, can swagger describe an output in anything other than Json schema? Not sure how the spec can describe content in any arbitrary media type. I dint see any use case for it in either thread. May be I'm missing something but it seems to me like we're trying to hammer that squire peg in.

dilipkrish on 28 Apr 2015

It has to use JSON Schema, but it can be translated to XML, and if it's a file, it can be said it's a file. Right now there's no general support for XSDs or other description formats.

webron on 28 Apr 2015

@webron Since this is closed, is there a bug to collapse the same path with multiple produces/consumes?

dilipkrish on 28 Apr 2015

@dilipkrish - I admit I don't know.

webron on 28 Apr 2015

Hi, I have encountered the same issue as @dilipkrish has mentioned, I have 2 resources which has identical path, but produces different response types, one for application/json, and one for text/plain.
The generated swagger definition is missing unless I comment one of the resource out.
I have been using swagger-core 1.5.0.
Any workaround before the spec change takes place?

ralf0131 on 17 Nov 2015

👍2

hi @ralf0131 it's not a spec bug, but it is a feature limitation. Please consider adding a comment to that repo with your usecase and desire to have it changed.

fehguy on 28 Nov 2015

👎1

I've faced the same issue. Am I right that there is no any workaround here except to change the path of one of the resources?
I use swagger-core 1.5.18.

beskrovnykh on 12 Mar 2018

I think this issue should be reopened, it is completely valid to have a custom content-type (@Consumes or @Produces), for example, a bulk operation that can even have parameters in addition to a requestBody that is different from another method implemented with the same path.
I think, it is necessary to support these cases in the spec without forcing to change the path.