LemmyNet
Improve API documentation
This seems to be the best option for API docs that I can find: https://github.com/juhaku/utoipa
It doesnt support the the pattern with Perform trait for API handlers. This pattern also doesnt serve any purpose in our code as far as I can tell, so I will get rid of it and use simple handler methods instead.
Another disadvantage is that we will have to specify the path separately in utoipa annotations, so the path needs to be present on the method itself, and in api_routes_http.rs. Unfortunately there seems to be no good alternative.
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?
Yes, I prefer the existing lemmy-js-client docs anyway. Those are already auto-generated from its codebase, here: https://join-lemmy.org/api/
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.
The paths and methods are mentioned, here's an example:
https://join-lemmy.org/api/classes/LemmyHttp.html#likePost
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.
I'd rather not add anything too custom, but typedoc does look like its supports some pre-made themes: https://typedoc.org/guides/themes/