Upgrade OpenAPI

[turt2live]

Currently we use 2.x - upgrading gets us a lot of benefits and appears relatively painless

[richvdh]

I found https://blog.stoplight.io/difference-between-open-v2-v3-v31 a useful introduction to the changes here.

[zecakeh]

Hi ! I'm interested in working on this, if no one else is currently doing it.

I already ran the swagger2openapi script to see how much work is involved. It seems like it didn't break much on the OpenAPI side, but it did some linting at the same time so it's gonna take some time to check that nothing was removed.

Would it be interesting to switch directly to OpenAPI 3.1? Afaict, the tools used all support it (RapiDoc for the UI and swagger-parser for the CI), however the README mentions testing with swagger-ui, which doesn't have support yet.

[richvdh]

I don't think we use swagger-ui any more (it's superseded by Rapidoc).

I'd be very excited to see work happening in this direction, however do have a look at matrix-org/matrix-spec-proposals#1446 (comment) which contains some notes on a previous attempt at this work.

[zecakeh]

Thanks I already took a look at this thread. I wrote a simple conversion script that at least keeps the licensing comments at the top.

I see that the check-swagger-sources.py script doesn't seem to be used or mentioned anywhere, but looks like a predecessor of validator.js? So I'm wondering if I should also update it for eventual changes.

[richvdh]

I don't think check-swagger-sources.py is a predecessor to validator.js - they have both coexisted for a long time. Still, I'm not entirely sure what the difference is, and it's true that check-swagger-sources.py doesn't seem to be used anywhere (and it doesn't currently pass).

So, I wouldn't block any upgrade job on maintaining check-swagger-sources.py - we can do that separately.

[afranke]

See also #8

[zecakeh]

I opened #1310 (still a draft). Feedback is very welcome.