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]

https://github.com/WeblateOrg/weblate/pull/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]

https://github.com/WeblateOrg/weblate/pull/12612 has been just merged. I would appreciate it if you could compare what you've manually crafted in https://github.com/WeblateOrg/weblate/pull/12585 to what it generates. We then need to customize the generated schema to match the reality.

[nijel]

I've made some cleanups in https://github.com/WeblateOrg/weblate/pull/12645 and https://github.com/WeblateOrg/weblate/pull/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.

[nijel]

https://github.com/WeblateOrg/weblate/pull/14246 is the next step. It uses OpenAPI in the documentation instead of manually maintaining it. It will need additional steps:

• Review the documentation if something is missing from the current docs.
• Update links from the rest of the documentation to the OpenAPI one (it uses different references for URLs).
• Remove the old docs.

I'm not sure what would be the best approach now. Do we want to merge #14246 and iterate over the remaining steps, or wait until we have all the bits ready?

[walpox]

Presently, are we talking about changes to the documentation contained in docs.weblate.org, the one built with Read the Docs and Sphinx? I am asking to verify we are not talking about changes to other places such as the API documentation provided by a deployed Weblate instance, like hosted.weblate.org/api/docs/.

If so, I would like to ask what the desired end goal is here. For example, let's say, to replace the current REST API page with content generated automatically from the OpenAPI schema (with sphinxcontrib-openapi). To improve that page by getting rid of manual maintenance and relying solely on Weblate's API codebase for this documentation.

After this is discussed and the picture a bit clearer, I will look into the steps mentioned in your comments, for example, for missing information in the documentation generated by the OpenAPI schema.

[nijel]

Yes, the goal is to avoid manually documenting the API. The pull request adds it to the API page duplicating the content temporarily.

[nijel]

Here it is rendered: https://weblate--14246.org.readthedocs.build/en/14246/api.html#openapi

[walpox]

Sorry for the late response, I have been busy with some other stuff...

I noticed some information is missing when using the Sphinx plugin for OpenAPI, such as the string in info.description.

I will review the codebase of this plugin to see if this is intended or rather a bug, and make appropriate fixes.

Thus, this issue should be moved to a later milestone because I don't think I will have time to review and prepare the changes for the next release of Weblate.

[nijel]

I've already removed it from the milestone as I've noticed the missing bits as well. Some of them are definitely caused by https://github.com/sphinx-contrib/openapi/issues/107.

[nijel]

The https://github.com/sphinx-contrib/openapi repo is not really receiving much of a maintenance, so I'm not sure if this is a viable approach. Therefore, I've modified https://github.com/WeblateOrg/weblate/pull/14246 to only keep track of the OpenAPI spec in the repository, but not include it in the documentation.

We still need to figure out how to deal with that. I'd honestly love to have the documentation based on the OpenAPI specs. I see some approaches:

• Use redoc only for the API documentation. This would make it hard to link from the rest of the documentation to the API one.
• Bring https://github.com/sphinx-contrib/openapi back to life by making it support OpenAPI 3 features.
• Add own conversion from OpenAPI to Sphinx to cover the bits we need.

[walpox]

As you say, it seems the sphinxcontrib-openapi extension doesn't have much active development.

In my opinion, having our own extension or fork to implement the missing functionality and render the contents inside Sphinx seems to be the way to go.

I will evaluate me starting development of this extension or fork by the end of the year. In the meantime, I suggest keeping the documentation as it is. At least, the OpenAPI spec is still available at /api/docs, with a good enough format.

[walpox]

I have finished the other project. Thus, I have free time I will use to work on this issue from now on.

If you want to add anything while I work on this (e.g. changed requirements), feel free to do so.

[nijel]

Thanks! The only new think that popped up is https://github.com/WeblateOrg/weblate/pull/15729. As mentioned there I don't think this is a good approach, but some of the points are definitely valid.