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 http://jsonapi.org/schema work as-is?
@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?
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.