REST API documentation

[cyrildewit]

Description

Documenting how our REST API works is mandatory. Consumers should be able to read which endpoints are available and what data they expect/output.

Documentation can be written in multiple ways. For example:

• Markdown files within the repository
• Word document or Googel document
• Using OpenAPI

What is OpenAPI

"The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service." From: OpenAPI Specification v3.1.0

Advice

Using the OpenAPI Specification to document how REST API looks really promising. One of the nice features of documenting our information in this format is the ability of machines to understand it. The documentation can for example be automatically generated. It also makes writing documentation easy since you have make use of the standardised features. The ecosystem of OAS is also quite big. Auto Generators, Converts, Data Validators, and many more tools are available. See https://openapi.tools/ for a complete list.

Design

OpenAPI description files

The OpenAPI descriptions should be stored somewhere. To keep it close to the source code, I would like to propose to store these files within this repository. This way we can keep track of previous changes. When changes are made to the actual REST API, contributors can immediately write documentation for it. We can then add for example validators that check if there are for example unnoticed breaking changes. Thus improving the quality of the software.

These descriptions can be stored in the following directory: /openapi.

[cyrildewit]

@Hoopless could you give your opinion on this and comment if you support the proposed idea? Thanks.

[cyrildewit]

https://swagger.io/docs/specification/authentication/

[JSTLWK]

I do support the location of the documentation! In the end there is 'Thus' instead of 'This'. Small typo.