API documentation

[juliusknorr]

We need a proper API documentation for the brand new rest API from #535. Proposals for tooling that could help provide a nice documentation is welcome 😉

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

[pixelipo]

Is there an official "Nextcloud" way of creating documentation for apps?

The easiest method is to just create a markdown file in code. However, I believe documentation should be accessible from within the NC instance itself.

There is already /settings/help page which hosts NC server documentation - why not expand it to include app-specific docs as well? It's just a placeholder anyway, since it hosts docs from core/doc/user as well as core/doc/admin. It could very well append app/deck/doc section.

P.S. Awesome work @Nebri and @juliushaertl creating the API!

[juliusknorr]

I think the API documentation could still be independently hosted somewhere else since it is nothing regular users will care about. The usual nextcloud documentation is build with sphinx, but I'd like to have something more API focused. Maybe with some examples like curl requests.

[b-m-f]

What about Swagger PHP?