Description
Request
Integrate OpenAPI checks into the validation of pull requests.
Motivation
The make lint-docs command is currently not part of any automation or validation so it is very easy for a pull request to unwittingly create invalid OpenAPI documents.
It's currently also possible to have pull requests that make changes in the specification but do not re-generate OpenAPI documents. The changes are therefore not caught until the next time the make transform-to-openapi command is run. Ideally this would occur within each PR so that contributors would immediately see the changed output and the linting results.
Additional info
Per https://docs.bump.sh/help/continuous-integration/#api-diff--validation-of-the-documentation-file it seems that the Bump.sh diff feature might provide some validation. We have more control over the linting rules used by the make-lint-docs command, however. Currently a lot of the linting rules are set to "warning" instead of "error" status to give us more time to take action on them: https://github.com/elastic/elasticsearch-specification/blob/main/docs/linters/redocly.yaml
There are also some warnings that are unlikely to ever be addressed, such as those described in #2806. We might want to exclude entirely from our linting rules if they're causing too much noise. Conversely there are rules related to missing descriptions that we'll likely want to turn into errors after we clean up all the pre-existing absences.