[FEATURE] Document REST APIs

[dbwiddis]

Is your feature request related to a problem?

As we build functionality into extensions, we should be documenting the APIs. I created example OpenAPI spec files for the sample extension (one in YAML, one in JSON) as part of #113. These can be viewed in any "OpenAPI viewer" including plugins for VS Code, Eclipse, and IntelliJ IDEA, along with some web options such as https://editor.swagger.io/

The OpenSearch APIs are here: https://github.com/opensearch-project/OpenSearch/tree/main/rest-api-spec and published at https://opensearch.org/docs/latest/opensearch/rest-api/index/, although these are manually maintained. There is ongoing discussion about automatic generation in opensearch-project/OpenSearch#3090

What solution would you like?

For now, make sure that we consider API generation just as important as JavaDoc generation. We should follow the above linked issue and synchronize our approach with OpenSearch.

What alternatives have you considered?

Waiting until the OS issue is decided on before generating anything. That creates a lot of technical debt!

Do you have any additional context?

This could potentially be something we can integrate into the Extensions Catalog. Or it might be totally out of scope there.