docs
docs copied to clipboard
flarum
Documentation for REST API use
Even if it's as much as there previously was on the docs for beta 7, at least that'd be something which would include getting an API key and performing basic requests.
For anyone looking for the beta 7 JSON API documentation page, an archived version is available on Archive.org.
@matteocontrini It can also be seen at https://github.com/flarum/flarum.github.io/blob/20322c0e6011e4f304ae7e95f41594a0b086bc27/_docs/api.md.
However, with the new documentation for the API, we'd like to provide better information on each endpoint, parameters required, etc... as the old docs only included the endpoints and could be a little confusing.
Some relevant discussion in this (now closed) PR https://github.com/flarum/docs/pull/76
Without getting into specific endpoints, I'm planning to add a page describing general use of the REST API (most importantly, how to authenticate and deal with CSRF stuff.
https://github.com/zircote/swagger-php might be exactly what we need to generate the docs from code.
where would we want to have the docblocks for each endpoint, in the routes file or maybe on each controller class file ?
I would prefer the controller files; that way, changes to the API would prompt changes to the docs, and the file would still be readable (if we add it in routes, 95% of the file would be docblocks). That being said, my opinion on this isn't strong at all.
Although that library looks great it generates an OpenAPI doc (Which is awesome). OpenAPI has issues in terms of documenting JSON-APIs properly, it can be done but the ones I've seen still usually end up missing something or being inaccurate in someway. With that said it would be better than what we currently have (no docs)
