API documentation

[D4nte]

Create API documentation (Thomas mentioned OpenAPI) for each service. Need to be close to the code to avoid deprecation (in code? File at root?)

[thomaseizinger]

Ideally, we would have some form of contract tests. I will gather a few resources around that.

[thomaseizinger]

My vision would be that at some point our APIs are documented using JSON hyperschema (https://blog.apisyouwonthate.com/getting-started-with-json-hyper-schema-184775b91f).

That is a specification that allows to describe (proper) REST APIs (with hypermedia and stuff).

I think for now, we are also fine with using OpenAPI (version 3). OpenAPI takes a more procedural approach that defines all the paths instead of relying on links. There is quite an ecosystem around OpenAPI.

Here is what I imagine:

• API description file in the root of each service (contracts)
• A tool to generate stubs from these contracts (so that we don't have to write the fake services ourselves)
• A tool that generates human-readable documentation from these contracts

[LLFourn]

"open source" added to force discussion

[D4nte]

IMHO: Not needed for opensource.

[D4nte]

To do once people start asking about how they can write their own application.