documenting some endpoints of the api

[niccokunzmann]

This is useful for me if I would like to provide 3rd-party services for Flarum.

[dsevillamartin]

We have internally discussed API documentation, and I think we saw that the best idea would be in-code documentation (as PHP comments). However, we haven't decided that.

A few things, if we do decide that we want the documentation to be in the current docs as simple text

• we'd want to have all the endpoints, not just /api/discussions
• the API routes would be in their own page, as the extend/routes page is for adding routes through extensions.

I'd wait for another core member to chime in here though.

[franzliedke]

Hi Nicco! 👋

While I agree with David that we want to move to something auto-generated from the source code as our source of truth, I still think having any API docs would be nicer than having none.

As @datitisev, this would have to be moved to a separate section of the documentation, though.

@flarum/core Any input on the best place for that?

[askvortsov1]

the API routes would be in their own page, as the extend/routes page is for adding routes through extensions.

I agree with this point: our extend docs should be for extension developers. IMO, a REST API documentation section should be moved out to its own section of the docs.

[tankerkiller125]

For sure this should be in it's own API sub directory something like flarum.org/docs/api should be fine in the end.

[luceos]

I love the approach Stripe made. They have extremely well thought out documentation on every topic. But they have an additional API doc for developers where not just endpoints are described (including their payloads), but also example objects are provided. https://stripe.com/docs/api

[tankerkiller125]

@luceos I found a vuepress theme that supports the example query/response area, but I don't know if it's possible to target specific folders/areas with a specific theme on vuepress or if it has to be global https://github.com/sqrthree/vuepress-theme-api

[dsevillamartin]

Here's a message I sent last year in a private channel about possible tools for API documentation.

For API documentation, we might want to use documentation tools such as Slate (https://github.com/lord/slate)
might be a pain to set up at first though

Or maybe something like Swagger UI (https://github.com/swagger-api/swagger-ui) which uses OpenAPI specification that can be generated by the Swagger Editor (https://github.com/swagger-api/swagger-editor, https://editor.swagger.io/)
though again, a pain to set up

There's also apiDoc (http://apidocjs.com/), demo @ http://apidocjs.com/example/, though it's inline and would require the documentation being in the Controller classes themselves (probably something we don't want to do)

Franz might prefer inline documentation

Franz: If we try something like this, I think co-locating the docs with the code is our only chance to keep them up-to-date. Though that does not have to mean the same file.
David: Do you mean the inline documentation ? If so, that's a good point.
Franz: Yep

There's also Stoplight Studio (https://stoplight.io/studio/) which integrates with Git, and Postman (https://learning.postman.com/docs/postman/api-documentation/documenting-your-api/).

[jordanjay29]

Closing for inactivity.

[aligajani]

Anything I can refer to for an API...please? Even if its half baked.....

[SychO9]

@aligajani checkout maybe https://github.com/flarum/flarum.github.io/blob/20322c0e6011e4f304ae7e95f41594a0b086bc27/_docs/api.md