Describe the Weblate REST API with OpenAPI

[walpox]

Describe the problem

There is not a problem to solve per se. The current API documentation is good. In my opinion, the proposed OpenAPI standard might be an improvement upon such documentation.

Describe the solution you would like

OpenAPI (formerly known as Swagger) is one of the most popular specifications to describe REST APIs formally. It allows developers to define the entire Weblate REST API with a root OpenAPI document.

Some advantages this standard might offer over the current API documentation are:

• Make it easier for developers to code their own third-party REST clients to connect to the Weblate REST API, by using tooling which generates code automatically based on the OpenAPI document.
• Make it easier to document the Weblate REST API:
  • The OpenAPI specification provides a standard way to document REST APIs. It should be easier to document the API when you can use a well-known syntax and keywords (structure), without having the API documentation written in free-form (.rst files).
  • Sphinx seems to have plugins to integrate with OpenApi. If they support version 3.1 of the specification, it should be possible to display the OpenAPI document directly within the Weblate documentation.
• It should facilitate automating testing of the Weblate REST API.

Describe alternatives you have considered

No response

Screenshots

This is how the Weblate REST API looks in Swagger UI:

Click to show image

In Sphinx with sphinxcontrib-openapi:

Click to show image

In Sphinx with sphinxcontrib-redoc:

Click to show image

Additional context

Compared to Swagger UI, the Sphinx plugins are missing information and seem to work worse. If we can get drf_spectacular to work with Weblate, it should be possible to offer the OpenAPI document programmatically and letting people use it as they please.

[nijel]

#12612 integrates drf-spectacular to Weblate. This gives some OpenAPI schema, but it is very likely incomplete and needs additional annotations to make it really a replacement for the current documentation. But I think it's the correct direction that will allow us to discard manually maintained documentation in the future.

[nijel]

#12612 has been just merged. I would appreciate it if you could compare what you've manually crafted in #12585 to what it generates. We then need to customize the generated schema to match the reality.

[nijel]

I've made some cleanups in #12645 and #12644, but there is still a lot to review and fix.

[nijel]

I've also added CI action to lint - https://github.com/WeblateOrg/weblate/actions/workflows/api.yml. It shows quite some errors and warnings for now: https://github.com/WeblateOrg/weblate/actions/runs/11126455162

[walpox]

It looks promising. I'm going to keep proposing changes to make the documentation better.