Note: my local Swagger UI container takes between 2.5 and 7 minutes to load the entire Weblate specification, with around 270 XHR requests. This is probably caused by the high number of $refs in the documents to keep things organized and DRY.

Thanks!

The annoying part of API documentation is keeping it in sync with code. It is easy to miss updating the list of fields in the docs when adding one to the serializer. Having a way to validate DRF implementation against docs would be great. Do you think something like that would be possible with OpenAPI when we decide to maintain it manually?

Maybe drf-spectacular would be a better approach in the end, so that all this can be generated (I guess some additional annotation in the code is needed for that)?

Also, have looked at options of integrating this into our existing documentation?

I agree that using an automated tool such as drf_spectacular is better in the long term for maintainability of the API documentation. Unfortunately, I couldn't get this tool to work in my local environment with Weblate code: it kept throwing exceptions.

I have tested the OpenAPI document in this PR with two Sphinx plugins and uploaded the corresponding screenshots in the linked issue. They are both a worse experience that Swagger UI... Still, if we can get drf_spectacular to work, we could use it to generate an OpenAPI document and link it in the regular API documentation. Like this:

That way, at least the OpenAPI document would be up to date with Weblate code, even if the API document page is not.

I'm closing this PR until I have enough Python experience to fix the issue with drf_spectacular to generate OpenAPI documents from Weblate source code.