I think this is a good idea, but we're not doing it right now. Probably a useful thing to consider in the future.

Change 617125 had a related patch set uploaded (by Pablo Grass (WMDE); owner: Pablo Grass (WMDE)):
[mediawiki/core@master] DNM: REST API: add ability to output openapi 3 spec

https://gerrit.wikimedia.org/r/617125

Change 617162 had a related patch set uploaded (by Pablo Grass (WMDE); owner: Pablo Grass (WMDE)):
[mediawiki/core@master] DNM: REST API: let Handlers expose body params, show them in openapi

https://gerrit.wikimedia.org/r/617162

Change 617162 abandoned by Pablo Grass (WMDE):
[mediawiki/core@master] DNM: REST API: let Handlers expose body params, show them in openapi

Reason:
This was a PoC but not meant to fly.

https://gerrit.wikimedia.org/r/617162

Change 617125 abandoned by Pablo Grass (WMDE):
[mediawiki/core@master] DNM: REST API: add ability to output openapi 3 spec

Reason:
This was a PoC but not meant to fly.

https://gerrit.wikimedia.org/r/617125

I would very much like this. I tried diving into the query-API on Wikidata today and I did not like the format of the current documentation at all. Confusing to say the least. Thanks to the telegram group I got my query working using the https://www.mediawiki.org/wiki/Help:Extension:WikibaseCirrusSearch extensions but they are not found anywhere in the generated API documentation what I could see.

In T221741#7346366, @So9q wrote:

I would very much like this. I tried diving into the query-API on Wikidata today and I did not like the format of the current documentation at all.

Note that the query API (api.php?action=query) and the REST API (rest.php) are entirely different things.

Pretty much the same as T323786: REST framework: Add support for outputting an OpenAPI (swagger) spec

Is it really about outputting OAS only? I would have assumed the ultimate goal would have been that MW REST API consumes a specification of the API in OAS document. That's at least my naive reading of the task title.