Generate a docs for properties that are a simple reference

[swallez]

Open API 3.0 doesn't allow attaching docs and additional properties to a $ref type definition. Because of this (and this was a forgotten TODO) many property descriptions were dropped in the OpenAPI output.

This PR fixes this by using a common/recommended workaround consisting in using a single allOf inline schema around the reference.

Fixes #5082.

@szabosteve can you verify that the doc generation pipeline correctly picks up this change?

Example (taken from the diff):

"chunking_settings": {
    "$ref": "#/components/schemas/inference._types.InferenceChunkingSettings"
}

Becomes:

"chunking_settings": {
    "externalDocs": {
      "url": "https://www.elastic.co/docs/explore-analyze/elastic-inference/inference-api#infer-chunking-config"
    },
    "description": "The chunking configuration object.",
    "allOf": [
     {
        "$ref": "#/components/schemas/inference._types.InferenceChunkingSettings"
      }
    ]
}

[github-actions]

Following you can find the validation changes against the target branch for the APIs.

No changes detected.

You can validate these APIs yourself by using the make validate target.

[szabosteve]

Thank you so much for this fix, @swallez! I asked the folks responsible for the docs generation process to verify if they can pick this change up correctly. I'll get back to you as soon as I have an answer.

[szabosteve]

@swallez The folks at Bump pushed a modification on their side to support the new input. Just checked and your fix works fine! Thank you very much for your work, it significantly improves the API docs quality!

Parameter descriptions like sevice and input_type, for example, were empty before your fix!

[szabosteve]

LGTM!

[github-actions]

The backport to 8.19 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.19 8.19
# Navigate to the new working tree
cd .worktrees/backport-8.19
# Create a new branch
git switch --create backport-5129-to-8.19
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 ef9f1da6e371f8681e1a603b6afc7637a0d704f0
# Push it to GitHub
git push --set-upstream origin backport-5129-to-8.19
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-8.19

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

[github-actions]

The backport to 9.1 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.1 9.1
# Navigate to the new working tree
cd .worktrees/backport-9.1
# Create a new branch
git switch --create backport-5129-to-9.1
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 ef9f1da6e371f8681e1a603b6afc7637a0d704f0
# Push it to GitHub
git push --set-upstream origin backport-5129-to-9.1
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-9.1

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