Improve API documentation about lemmy-docs HOT 6 OPEN

Unfortunately I was wrong, the Perform traits are absolutely necessary so that the same API handlers can be used for HTTP and websocket. Thats because HTTP handlers need to return HttpResponse, but websocket requires plain json structs. There might be another solution by using middleware to rewrite the responses, and that way use API handlers that work with utoipa documentation macros. But thats probably not worth the effort.

So I think the better solution to document the HTTP API would be to generate docs in lemmy-js-client, like we are already doing for websocket. It already has the necessary data (structs, HTTP methods and paths). What do you think @dessalines?

from lemmy-docs.

Yes, I prefer the existing lemmy-js-client docs anyway. Those are already auto-generated from its codebase, here: https://join-lemmy.org/api/

from lemmy-docs.

The current API docs are fine, but they are only for websocket. They arent useful at all if you want to use the HTTP api, because HTTP methods or paths arent mentioned. So when building LemmyBB I had to look these things up in the source code. This is not an option for people who are not familiar with Rust, and makes it unnecessarily difficult to develop Lemmy clients. Everyone is familiar with HTTP, and is unlikely to learn websocket for a simple project. Thats why I believe we need two sets of API documentation, one for websocket and one for HTTP.

from lemmy-docs.

The paths and methods are mentioned, here's an example:

https://join-lemmy.org/api/classes/LemmyHttp.html#likePost

from lemmy-docs.

Oh thats very easy to miss, I didnt notice that at all before. Can we change the color scheme to emphasize it? Or even switch to a different frontend? The one used by Peertube looks very nice.

from lemmy-docs.

I'd rather not add anything too custom, but typedoc does look like its supports some pre-made themes: https://typedoc.org/guides/themes/

from lemmy-docs.