[DOC] Generate API documentation from spec

[dblock]

What do you want to do?

The https://github.com/opensearch-project/opensearch-api-specification repo contains and publishes the machine-readable reference of the APIs in OpenAPI format, along with runnable tests that execute an actual version of OpenSearch. The spec is work in progress, but has some solid coverage of core, and soon to have coverage of plugins before EOY 2024. The spec also supports description, x-version-added/removed/deprecated fields, and much more.

We propose to generate the documentation reference from spec instead of authoring it by hand.

1. Author a basic tool in this repo (probably ruby since the jekyll ecosystem is all Ruby) that walks the spec.
2. Identify missing documentation that is documented in the spec.
3. Identify missing specs for APIs that are documented here.
4. Bridge the gaps between spec and docs, including https://github.com/opensearch-project/opensearch-api-specification/issues/403 and https://github.com/opensearch-project/opensearch-api-specification/issues/120.
5. Replace API reference with generated docs that combines humanly authored content with generated parts.
6. Automate the update process. With every API change a PR will be opened in this repo updating the generated docs.