search

Scille / parsec-cloud

Open source Dropbox-like file sharing with full client encryption !
https://parsec.cloud
Other
263 stars 40 forks source link

Add documentation for the Administration HTTP API #6047

Open mmmarcos opened 6 months ago

mmmarcos commented 6 months ago

The Administration HTTP API should be documented in a way that is linkable and searchable without having to read the source code. It should go in a dedicated document, different from the user and admin guides.

There are many examples out there, see for example Keycloak's documentation:

1. API description

In general, there are two approaches depending if the API is first implemented in code (code-first) or described to generate the code (design-first).

Since the API is already implemented, we should find a way to easily generate (and keep in sync) the API description based on the source code (see server/parsec/api/rest.py).

We should probably use OpenAPI since it is the de facto standard for describing HTTP APIs.

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. [...]

An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.

See OpenAPI's Getting started and Best Practices guides.

2. Documentation generation tools

Research and compare tools to generate documentation such as Redoc (formerly Swagger) or Fern.

See https://tools.openapis.org/categories/documentation.html

The Future

OpenAPI descriptions should enable ideas for further improvements (validators, test automation? changelog generation?).

https://tools.openapis.org/

touilleMan commented 6 months ago

We should probably use OpenAPI since it is the de facto standard for describing HTTP APIs.

Great news everyone: FastAPI is based on OpenAPI \o/

I guess only our REST API can be effectively documented with this (given the RPC API is not based on JSON and only use a single endpoint for all commands), but that's okay given the RPC API is only for client/server communication so can be considered internal to Parsec (by opposition of the REST API which is REST specifically to be usable by 3rd party !)