Adds examples to schema.json and OpenAPI outputs

[siamakp-elastic]

This feature scans All the API folders in the specification to locate API request and response examples. It then adds the 'examples' info to schema.json and to the OpenAPI JSON files.

[swallez]

Please add doc-comments explaining what these are.

[siamakp-elastic]

The comment above the class references the OpenAPI spec page which fully explains the fields.

https://spec.openapis.org/oas/v3.1.0#example-object

[swallez]

This will output the example as a JSON string, e.g. "value": "{\"foo\":\"bar\"}" instead of "value": {"foo": "bar"}.

Is this what we want? The OpenAPI spec shows that this should be a value and not a value-in-a-string.

[lcawl]

From a docs point of view, it doesn't seem to matter. For example when I run our current overlays, I get both variations and they both publish fine. For example:

 "ClusterPutComponentTemplateRequestExample1": {
        "summary": "Create a template",
        "value": {
          "template": null,
          "settings": {
            "number_of_shards": 1
          }...

as well as:

     "ClosePointInTimeResponseExample1": {
        "description": "A successful response from `DELETE /_pit`.",
        "value": "{\n  \"succeeded\": true, \n  \"num_freed\": 3     \n}"
      },

If one of these is preferable from a client point of view, that would be good to know. Otherwise from a docs point of view I'm good with whatever is easiest.

[siamakp-elastic]

In the example files, I commonly saw JSON strings, but there were also instances of YAML objects. For consistency, I have converted everything to JSON strings.

[lcawl]

I've rebased and marked the resolved comments... I think this is ready for re-evaluation

[github-actions]

The backport to 8.x failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-8.x 8.x
# Navigate to the new working tree
cd .worktrees/backport-8.x
# Create a new branch
git switch --create backport-3737-to-8.x
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 e9bc80f1c92fcfa3dd2dae3deb87177b0855e35a
# Push it to GitHub
git push --set-upstream origin backport-3737-to-8.x
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-8.x

Then, create a pull request where the base branch is 8.x and the compare/head branch is backport-3737-to-8.x.

[github-actions]

The backport to 8.18 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-8.18 8.18
# Navigate to the new working tree
cd .worktrees/backport-8.18
# Create a new branch
git switch --create backport-3737-to-8.18
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 e9bc80f1c92fcfa3dd2dae3deb87177b0855e35a
# Push it to GitHub
git push --set-upstream origin backport-3737-to-8.18
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-8.18

Then, create a pull request where the base branch is 8.18 and the compare/head branch is backport-3737-to-8.18.

[github-actions]

The backport to 9.0 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-9.0 9.0
# Navigate to the new working tree
cd .worktrees/backport-9.0
# Create a new branch
git switch --create backport-3737-to-9.0
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 e9bc80f1c92fcfa3dd2dae3deb87177b0855e35a
# Push it to GitHub
git push --set-upstream origin backport-3737-to-9.0
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-9.0

Then, create a pull request where the base branch is 9.0 and the compare/head branch is backport-3737-to-9.0.