Use Redocly CLI to validate OpenAPI definitions

[zecakeh]

When I worked on upgrading the OpenAPI data (#1310), I found swagger-parser unreliable, mostly because this tool found errors that swagger-parser didn't report. There are also other benefits for using this:

• It's a linting tool, so other rules can be enforced if wanted
• The errors reported are much easier to understand than with swagger-parser
• It has a rule that checks that examples are valid according to the schemas, which could replace the (currently unused) check-swagger-sources.py script. However to make it work we need to remove $refs inside examples, as it is not spec compliant.

I found this tool with this list: openapi.tools. Of the tools that advertise support for OpenAPI 3.1, only two work with our definition files:

• Redocly CLI
• Spectral

They both have similar features so we could use Spectral instead, but I found Redocly CLI visibly faster (although it's a matter of seconds in both cases). Another advantage for some is that Redocly CLI integrates with VS Code It turns out Spectral too.

The configuration file here deactivates the minimum number of rules to make our definitions pass validation. They can be re-enabled by fixing the errors reported in subsequent PRs.

Signed-off-by: Kévin Commaille zecakeh@tedomum.fr

Preview: https://pr1558--matrix-spec-previews.netlify.app

[KitsuneRal]

The less we have things invented around OpenAPI, the more we can focus on making Matrix awesome.