How does one document a JSON:API about json-api

[lindyhopchris]

As the creator of Laravel JSON:API, I'm interested to see what people say here.

FYI there is an intention for Laravel JSON:API to produce Open API specs. The only thing that's blocking it really is available time on open source work. Plus I find it difficult to prioritise, because the personal projects I use Laravel JSON:API don't (at the moment) need OpenAPI spec files.

There's a rather lengthy discussion about it here, in case you haven't seen it: laravel-json-api/laravel#19

[Floppy012]

There's a rather lengthy discussion about it here, in case you haven't seen it: laravel-json-api/laravel#19

I have seen that issue and tried it out with the example project of Laravel JSON:API. It generates an OpenAPI spec file as expected, which does work but gets cumbersome really quickly.

Generating a client from that, currently doesn't work really well as the response bodies are incomplete (for example: included is missing. I know, it's still in development). But even if it were complete I would have to extract data from the included array using relationships data.

Example

const postResponse = await PostsService.postsShow(1, ['author']);  // the array represents the "include" query parameter

const author = postsResponse.included
    .filter((i) => i.type === postResponse.relationships.author.data.type)
    .find((i) => i.id === postResponse.relationships.author.data.id)

I know there are tools like json-api-merge. But they would only return me an untyped (any-object).

Our current solution

Currently we use Laravel-Data to work with data in regards to our API. We have a laravel package that generates an OpenAPI spec file using information from our controllers, attributes and the DTO class structures.

We then generate a Typescript client from that OpenAPI spec file and use that to interact with our backend. One of the major benefits is, that if a backend dev changes something in regards to the API, we immediately see where we have to adjust code in our frontend due to TypeScript or SAST throwing errors at us.

[jelhan]

Two patterns are available to document your JSON:API as already mentioned in this thread:

1. Human readable documentation focused on existing a) entry points to the API, b) available resource objects and the attributes and relationships of those, and 3) implementation-specific semantics (e.g. filtering strategy, supported side-loading of related resources etc.).
2. Machine readable documentation using OpenAPI specification.

An API could provide only one of them, both or even none. The documentation could be written by hand or generated automatically. Existing tooling highly depends on the tech stack chosen by the project. This is nothing to be solved by the JSON:API specification itself in my opinion.

[jelhan]

I'm going to close this issue. Feel free continuing the topic in the discussion forum.