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?



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.


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.