OpenAPI 3.0 spec that conforms to JSON:API

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!

1 Like

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.

What is the difference between this and https://github.com/json-api/json-api/blob/gh-pages/schema ?

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