Skip to content


Subversion checkout URL

You can clone with
Download ZIP


Support for well-known discovery url #70

gregmac opened this Issue · 7 comments

4 participants


Right now, swagger-ui (or any Swagger-compliant client) has to know the exact URL of the swagger ResourceListing in order to display the results. As far as I know, every implementation does this differently.

It would be nice if you could point swagger-ui at any swagger-compliant API base path (eg, and have it "just work", regardless of who implemented the server or what language/library it was done in.

So my proposal is we add to the spec that swagger-compliant APIs always have a /swagger.spec or something along those lines, which implements (or redirects to) the ResourceListing.

TBD: the discovery URL(s) to use, which would work across all platforms

Note, I think this has value being part of the spec, rather than just swagger-ui, but this could also just be a convention that swagger-ui in particular uses. But my logic is if it takes off it would become a de-facto standard anyway, so why not put it in the spec.


I'm all for a /api-docs/resources.json endpoint but not for /resources.json to live at the root of my app


There are two challenges--one, some folks don't have control over the path that their webapp is deployed. It may be the ROOT webapp (so would be valid), others might require the version in the path, like Wordnik @ So I think setting a global discovery URL is a difficult thing to get adopted.

We can change convention but it may still lead to paths like /v4/api-docs/resources.json which is not universally consistent.


Perhaps we could have a link tag in the html pages that shows the discovery url

<link src="/v4/api-docs/resources.json" type="application/swagger-discovery" />

I think I may have used a bad example, I did not mean it has to be the root of the application. For Wordnik, I'd say to a developer that the "root" of the API is really (or, and so that is what I should be able to type into swagger-ui. From there, it should "discover" /resources.json.

Another way of saying this, as an end-user of the API, has meaning to me, because it's the base of basically all API calls. In fact, my code probably has something like var baseUrl = ""; somewhere in it. Assuming I know nothing about what Swagger is, this /resources.json I have to stick on the end when I'm using this crazy interactive documentation thing is just some (to me) meaningless cruft the documentation tool needs or it complains.

Per @casualjim's suggestion, maybe discovery can be multiple parts:

  • Check the URL entered for a ResourceListing
  • Check the returned response for <link type="application/swagger-spec">
  • Check the URL entered + /resources.json for a ResourceListing

However, I'd suggest adding the /resources.json (or something similar) is a good start, and pretty easy to implement.


seems like returning a discovery URL in the headers might suffice, rather than an actual link response per @casualjim's suggestion. Then the payload will be unaltered.

Would be a shame, though, to send on every response from the API because of increased bandwidth. Perhaps just sending in the GET from the root resource? Thoughts on that?


is there any way to change the json provider fromcom.fasterxml to com.codehaus in swagger configuration.


@vsapram both can live in the same environment but you can't just configure swagger to use the older package. There are lots of changes in jackson after it moved to com.fasterxml.

@fehguy fehguy closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.