Add API examples in multiple languages

[lcawl]

priority: high
effort: high

🚀 Feature Proposal

Relates to elastic/docs-builder#55, but specifically in the automated API docs context.

In the old documentation system, we enabled users to copy examples in multiple languages. From a quick test, it seems like we can do the same in Bump.sh by using x-codeSamples.

The outstanding work IMO would be to (1) talk to @miguelgrinberg about the feasibility of using existing converter tools to generate these variations from our examples, then (2) investigate whether the automation @siamakp-elastic added for incorporating the request and response body examples could be extended to add these x-codeSamples too. From a brief conversation with @miguelgrinberg it seemed like perhaps these language-specific examples could be generated as part of the pipeline for generating the OpenAPI (i.e. they wouldn't necessarily need to be checked into the repo anywhere).

Motivation

API examples have been copied into this elasticsearch-specification repo from the Elasticsearch documentation per #2482
Those examples will be incorporated into the schema.json and OpenAPI output per #3737

If there is still "demand for more extensive examples for language clients" and "these auto-generated API request examples [are still seen] as a great way to fulfill this customer request" per elastic/docs-builder#55 (comment) then this seems like a pretty good next step for our API docs.

Example

In the old API documentation, the language selector looked like this:

For example: https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-exists.html

In the new API documentation, it looks like this:

To do a test of what an example with a request body looked like, I created elastic/kibana#220449, which displays as follows:

That seems like a nicer layout that what is automatically generated by default.

For example: https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-exists

This proof of concept used the following files: https://github.com/elastic/elasticsearch-specification/tree/main/specification/_global/exists/examples/xCodeSamples
... which are applied to the OpenAPI via an overlay in https://github.com/elastic/elasticsearch-specification/blob/main/docs/overlays/elasticsearch-shared-overlays.yaml but the longer-term solution should not rely on fragile overlays.

[lcawl]

Something to consider if we start adding these x-codeSamples more broadly is whether we want to have any advice about whether the examples that exist in multiple languages should be the same or whether it matters if they vary (i.e. Java example accomplishes something completely different that the console one). And any other guidelines around, for example, how many of these are appropriate for a single operation and what the dropdown-label should contain (if not using the default which is just the language).

[swallez]

Work is underway in PR #4371

[lcawl]

The additional examples are now live in https://www.elastic.co/docs/api/doc/elasticsearch-serverless/ and https://www.elastic.co/docs/api/doc/elasticsearch/

For example: