I do not see how critisms for the JS API docs are relevant for my openapi documentation.
This documentation aims to solve all those problems in a language agnostic way. It descibes the endpoints, the request object, the status, the response object, the authentication needed in visual/text. It allows you test it right from the browser, allows you to copy a working curl command, search for endpoints based on keywords, allows you to import the entire spec into postman/alts.
I ve never had any problems with CF instances but I mostly test with voyager.lemmy.ml
This could use indeed some work
openapi spec allows one to specify the authentication, this has not be done already because there is an open issue to include auth in
lemmy-js-client
(I use this to generate the spec) + Need to figure the best approach to convey “elevated” auth endpoints. Endpoints like GetSite where authentication enhances the response.They are actually summaries, they are fine imo. There is an open issue to add the descriptions though.
Yes indeed, things like this should be documented in the description.
This is explicitly mentioned on every request, visually and in the spec.
Query is mentioned when they are query parameters, else it just a request body. This is pretty clear in the text (spec) or visually imo.
GetPersonDetails
is the name of the object if you scroll all the way to the bottom you can inspect it. This more clear in the spec.There is not a single endpoint missing nor its requests.
This could be improved.
Status codes? or the 400 lemmy error? ex:
{ error: "report_reason_required" }
Status codes are the same everywhere, 200/201 or 400 with Lemmy error as response. There is one exception that is 401 that can be thrown for every auth required endpoint where auth fails. But these are standard. Ig this should documented.Now the “LemmyErrorTypes”. This could be improved, but it is hard to, not possible to be automated and tedious to add and frequently changes.
Thanks for the feedback.