I saw an older post from 2015 about documentation your API, and some sporadic comments since then about using OpenAPI to document a JSON:API compliant API. Since it’s been a few years, what are considered the best practices now? We have been documenting in OpenAPI prior to looking at adhering to the JSON:API spec, so that’s what we’re used to, but I am curious as to what is recommended once going the JSON:API route
1 Like
It’s all about the API clients. If your clients are expected to know about JSON:API, then you can just document the resources and the standard JSON:API operations on those resources (as well as all relevant semantics).
Here is an example of recent API documentation I have created for our company (part of a larger ecosystem). Make sure to also take into consideration the common specs it is based on (linked to at the top). For a free-standing API spec, I would inline those common specs.
Here is an example for another API I have created. It’s a bit older, so there are some inconsistencies compared to how things are done in first spec that I would fix if I had the time (or had created it now), but there are two things to look out for here:
- It’s a free-standing API (not part of a larger ecosystem), so some of the common specs mentioned above are inlined here
- API clients for this API do not necessarily know anything about JSON:API right off the bat, so the request and response bodies are documented. It’s a bit more work (OpenAPI is not as expressive as I’d like regarding re-using definitions), but possible.
Both of the specifications allow you to download the OpenAPI file if you want to have a look at it (see download button at the top).
4 Likes
Thanks a lot for sharing that examples! Very helpful.
May I ask which tools you used to generate that documentation?
Thanks so much for the response! Some great food-for-thought 
Not sure what you mean by “convert from JSON:API to OpenAPI types”. If you download the OpenAPI definitions for the examples I linked to (see the “Download” button at the top of the docs), you can see the OpenAPI documents used to generate the documentations. They’re not perfect, but good enough for my purposes.
1 Like
@cmeeren thanks for the response.
Yep, I see openapi spec and I checked it.
What I cannot understand is how you could have an json:api API and openapi documentation simultaneously? Aren’t those standards incompatible?
JSON:API is a specification for the format of an API. How are requests and responses structured, semantics of response codes, etc. It has nothing at all to do with how APIs are documented.
OpenAPI, on the other hand, is purely a specification format that allows you to write machine-readable API specifications, which tools like ReDoc can turn into human-readable documentation like those I linked to.
JSON:API and OpenAPI are completely orthogonal. Or course, whether OpenAPI is suitable for specifying/documenting JSON:API-based APIs is another matter. As you may see on this forum, there is some friction. OpenAPI is more geared towards explicitly specifying paths/verbs with their request/response bodies, status codes, etc… The big benefit if JSON:API is that it has a lot of this locked down, so JSON:API-based APIs may find it sufficient (as I have done it) to simply document the resources and the standard JSON:API operations.
If you find that OpenAPI is not suitable, you may want to look into RAML or API Blueprint, two alternatives to OpenAPI for specifying/documenting APIs.
2 Likes
@cmeeren right, thanks a bunch as well.
And a last question regarding your (extremely valuable) examples then:
Say /uploadFileRequirements endpoint. Is it json:api?
Why I’m asking:
this is how it’s http 200 response typed:
responses:
"2XX":
description: Ok
content:
application/json:
schema:
type: object
required:
- maxFileBytes
- allowedFileExtensions
properties:
maxFileBytes:
type: integer
format: int64
example: 104857600
description: The maximum file size in bytes
allowedFileExtensions:
type: array
items:
type: string
description: >
The allowed file extensions, without the dot (`.`). Case
insensitive.
example:
- jpg
- jpeg
- png
- avi
- mov
- mpg
- pdf
Obviously, this very response as-is is not valid json:api as it does not even have a root data property.
So, as you documented your api, did you imply that every typed response is in fact a valid json:api but with no json:api root properties documented?
In that case, how would you document meta?
1 Like
That endpoint is explicitly specified as not JSON:API:
/uploadFileRequirements:
get:
summary: Get file requirements
description: This is not a JSON:API endpoint.
If you see one of the specs the spec is based on, you see that it says this:
1 Like