@thomassittig @ThisIsFlorianK Yes, I think
it will serve users better if you provide a proper high-level documentation,
which can't be done in Swagger since everything is resource oriented. And since
machines consume APIs, provide them with JSON-LD/Hydra enriched APIs.