After searching and searching online for an example of an OpenAPI 3.0 spec that conforms to JSON:API and coming up short, I decided to give it a shot myself.
I would appreciate any feedback!
Great stuff - What would need to change in OAS3 vs JSON:API to make this easier?
Well, this isn’t specific to trying to implement JSON:API, but one of the things that bothers me about OAS3 is that I cannot override a description when using a schema reference. I want to be able to describe the schema but then provide an implementation-specific description when I reference the schema.
Is OpenAPI 3 a requirement, or are alternatives an option for you? I worked with RAML 1.0 for a while, and it was much more expressive than OpenAPI 3.
That said, the tooling available for RAML 1.0 wasn’t that great, and I ended up switching to OpenAPI 3 for better documentation generation. (I’m not currently using any tooling for code or test generation, or other runtime support; the specifications are just documentation at this point.)
All of that was before I started looking at JSON:API, though.
Yes, for my organization we have decided to standardize on OAS3.
While a schema for a JSON:API response is useful, it doesn’t provide a good place to hang descriptions of everything a caller needs to know.
For existing APIs (with lots of non-JSON:API portions; in my case), something like OpenAPI is still pretty useful.
Here’s a good article describing the differences - https://apisyouwonthate.com/blog/json-api-openapi-and-json-schema-working-in-harmony
The best example I found and the method I applied is the one developed by Alain Crosswell from the Columbia university.
An example can be found here (The components definition can be found in lines L4394-L4589):
1 Like
Please note that the schema is not written manually but autogenerated using Django REST Framework JSON API. Documentation for generating such a schema if using the framework could be found here.
v3.1 now allows to add summary and description beside $ref keys.