Jaxrs defined extension mappings interfere with swagger.json

[sg-ad]

Hi,

I'm not sure if this is something that should be fixed or simply documented. I've found that if Jaxrs has been configured with explicit extension mappings (ex: for JSON), it makes it impossible to access the new Swagger resource swagger.json. It's because the /swagger.json will get rewritten to /swagger by Jaxrs, which will no longer resolve to the API listing resource. The same happens if you have a yaml extension mapping defined.

One workaround is to extend the ApiListingResource, map /swagger and internally call either getListingJson(...) or getListingYaml(...).

Cheers,
Sebastien

[webron]

Could be the hour for me, but I don't follow you.

[sg-ad]

Sorry I wasn't clear. The JAXRSServerFactoryBean allows you to specify some extension mappings where you map an extension to a content-type. So you can say that all paths ending with .json extension are mapped to application/json content-type. These mappings are used by a Jaxrs request pre-processor that will update the Accept header to include application/json as an accepted content-type if the request path ends with that extension.

Jaxrs will follow this update with a removal of the .json extension from the path. So at the exit of the pre-processor, the request path is now .../swagger instead of .../swagger.json, so it no longer resolves to the resources exposed by ApiListingResource since they explicitly check for the extension.

So I wonder whether this would make a candidate for configuration or simply a case of documentation.

Caveat: judging from the few hits I get when searching, I don't think that configuring extension mappings in Jaxrs is a very widely used feature.

[webron]

Whether it is or isn't, it may still be worth investigating. Just keep in mind that the usage of swagger.json and swagger.yaml is based on the standard recommendation specified in the Swagger specification to end up with a common name for the documentation (similarly to the /api-docs in previous versions).

[sg-ad]

Good point. I guess if one wants their API to be discoverable by Swagger-knowledgeable tools, changing the usage won't be a very good workaround. Another (somewhat rudimentary) possibility would be for one to expose the Swagger definitions with a different endpoint on a different root than the rest of the API /spec/swagger.json while the API itself exists under /api/. This assumes that there are no extension mappings configured on /spec/ endpoint. Besides being counterintuitive, would this violate any explicit or implicit convention?

[webron]

Funny you should mention it. The specification does not mention where it should be hosted, and then came this - OAI/OpenAPI-Specification#393. It doesn't affect this version, but may affect future ones.

[sg-ad]

Thanks for pointing that out. I'll be curious to see how it develops.

I see you also referenced to #1145 - that basically brings in the workaround that I have now into the fold of Swagger directly. That fix will solve my issue quite nicely. I'm not very clear on the release process, so any idea when it might make it into a release? In the meantime I can continue using my workaround, so there's no particular rush for me.

Thanks for the help, and thanks for such a great tool!

[webron]

For easier reference, this should now be resolved by #1172.

[webron]

Well, not now, but will be resolved with it is merged.

[webron]

This is resolved as the PR is merged.