OpenAPI 3.0 spec that conforms to JSON:API

1

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!

2 Likes
2

Great stuff - What would need to change in OAS3 vs JSON:API to make this easier?

3

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.

4

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.

5

Yes, for my organization we have decided to standardize on OAS3.

6

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

7

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.

8

Here’s a good article describing the differences - https://apisyouwonthate.com/blog/json-api-openapi-and-json-schema-working-in-harmony

9

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
10

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.

11

v3.1 now allows to add summary and description beside $ref keys.