[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 [FEATURE] Require, standardize and import descriptions. opensearch-api-specification#403 and Incorrect server versions for the API models opensearch-api-specification#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.

[nhtruong]

To provide some context for those not familiar with the API Spec repo:

• Each of our spec test (aka a test story) provides a narrative that can be used to generate guides with setup, and tear down steps. Since we've built the test framework ourselves, we can also modify it too support generating guides in different programing languages.
• We should treat the spec as the source of truth. Technical details like the data structure and description of a query param for example, must be updated in the spec first. The update in the spec then will be propagated to the generated clients (in terms of method documentation and data typing) and the document website (The affected query params table will be updated instantaneously). This will keep the clients and the docs always up-to-date and consistent.
• We can also work with devs from the docs repo on how to consume the spec. Say if there's an article on how to search on OpenSearch and it includes a table with all query parameters for the search endpoint. Instead of writing and updating that table by hand, we should automatically generate that table from the spec.

[kolchfa-aws]

Once this is implemented and all clients are generated using the spec, it'd be nice to add a dropdown to all code blocks that users can use to choose the language for the code block. That way, client documentation can be integrated with the REST documentation.