search

flarum / docs

Flarum documentation.
https://docs.flarum.org
MIT License
70 stars 132 forks source link

Documentation for REST API use #44

Open dsevillamartin opened 5 years ago

dsevillamartin commented 5 years ago

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.

matteocontrini commented 5 years ago

For anyone looking for the beta 7 JSON API documentation page, an archived version is available on Archive.org.

dsevillamartin commented 5 years ago

@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.

jordanjay29 commented 4 years ago

Some relevant discussion in this (now closed) PR https://github.com/flarum/docs/pull/76

askvortsov1 commented 3 years ago

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.

askvortsov1 commented 3 years ago

https://github.com/zircote/swagger-php might be exactly what we need to generate the docs from code.

SychO9 commented 3 years ago

where would we want to have the docblocks for each endpoint, in the routes file or maybe on each controller class file ?

askvortsov1 commented 3 years ago

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.

tankerkiller125 commented 3 years ago

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)