Using swagger with jsonapi definitions?

I’m planning to use jsonapi conventions for a REST API designed and documented with swagger. Although I could inline the jsonapi definitions there (e.g., for error, meta, etc), it would seem better to reference them in an external doc.

First, does that sound right?

Second, has anyone done this? If so, any tips? Do I need a yaml version of the schema, or will work as-is?


1 Like

will work as-is?

No. Swagger doesn’t support the full set of JSON-Schema attributes (e.g. “oneOf” is not supported) :disappointed:

@reece were you able to solve this?

@jlangley, can you help me with this…
We also have a requirement to document our JSON API using Swagger. Can you give couple of samples as to how to achieve this.

Suppose if I have article model (from jsonapi with attributes title and relationships author and comments and couple of endoints, /api/articles (which returns paginated articles) and /api/articles/1 which returns a single article, how should the swagger models look like?
What should be the response model for the above endpoints?
How should sideloading (include=authors,comments) be represented in swagger responses?

Hi Reece , did you managed a way to make this works ? i have similar situation, i am using a python frameworks that supports json API and i need to add a swagger documentation for my APIs.

I gave up on jsonapi with swagger/openapi.

OpenAPI 3 (not yet released) claims to support a few more of the json schema elements, including oneOf. I’m unsure whether that’s enough to enable jsonapi.

Also, bear in mind that tools to actually use OpenAPI 3 will naturally lag that release.

I would love to see full convergence of openapi, json schema, and jsonapi, with a good example!


JsonApi and hypermedia as a whole are orthogonal to OAS/Swagger fundamentally. It is very simple, the foundational element of the OAS specification is the path, and while in hypermedia APIs it is the vocabulary of the hypermedia.

Some elements could be incorporated, but there is no way to fundamentally map one to another without changes to either of those basic properties.


Hello there !

Same here. I need to document a JSON API compliant API with Swagger 3 / Open API.
Does anybody know if it’s feasible ?

Thanks !


Sorry Geoffroy, but water (Hypermedia) and oil (OAS 3) still don’t mix. They are fundamentally intractable as currently designed.

1 Like

Too bad ! Does anybody know any alternative to nicely document a JSON API ?

My favorite is an ALPS profile combined with a JSON Home document. This allows a simple browser to be implemented (link HAL Browser) for documentation exploration and sandboxing.

For those who come this way again, here are two links are closer to what I was looking for.

External references now work in the tools that I use, so it seems likely that one can centralize the json api schema definitions to be used within an openapi schema.

i write a jsonapi-swagger generator use rswag.

hi, i have updated jsonapi-swagger gem. you can generate a swagger.json through json resource and browse doc through swagger ui .

1 Like