Document Best Practices and Tools

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

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).

1 Like

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 :slight_smile:

@jelhan I use ReDoc, as linked to from below the left-hand menu on the specs.