🚀 Feature Proposal

Currently, the method/path information and the authorization information of the endpoints are stored in the description field of the OpenAPI spec generated for docs. Ideally, these should be stored in separate fields, which requires extending the spec with two new fields. Currently, these are stored like this:

        "summary": "Get aliases\n",
        "description": "**All methods and paths for this operation:**\n\n<div>\n                      <span class=\"operation-verb get\">GET</span>\n                      <span class=\"operation-path\">/_cat/aliases</span>\n                      </div>\n                    <div>\n                      <span class=\"operation-verb get\">GET</span>\n                      <span class=\"operation-path\">/_cat/aliases/{name}</span>\n                      </div>\n                    \n\nGet the cluster's index aliases, including filter and routing information.\nThis API does not return data stream aliases.\n\nIMPORTANT: CAT APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API.\n\n## Required authorization\n\n* Index privileges: `view_index_metadata`\n",
        "operationId": "cat-aliases",

• A new extension – for example, x-variations – would store the method/path info.
• Another one – for example, x-req-auth – would store the required authorization information. Unfortunately, the security schemes OpenAPI provides don't match our needs.

Motivation

The path variations were added to the description field for a practical reason (per #4277). For specifications that are associated with multiple paths and methods (e.g. BulkRequest.ts), each unique path and method ("operation") appeared separately in the OpenAPI document, which though accurate meant a lot of duplication and therefore usability concerns. To improve this, the OpenAPI generator for docs currently includes only one variation (the longest one?) and the others are listed in the operation's description. Per #4303 the missing authorization details were likewise added to the operation descriptions.

However, storing this information in the description is no longer ideal. It makes programmatic analysis difficult, since the field mixes descriptive content with metadata. For example, identifying endpoints that lack a proper description becomes problematic when the description field also contains method/path or authorization details.

Proposal

Upon generating the spec for the docs, the generator would put the method/path information into an x-variations field (for example, an array of strings) and the authentication information into an x-req-auth field (likewise should probably be an array of strings) instead of the description field.

NOTE:

• If the movement of the specifications to the Elasticsearch repo (or some other planned reorganization) results in a better solution for #4277 (i.e. there will be a way to uniquely describe each endpoint), then there will no longer be a need for x-variations and each endpoint can have the appropriate details and examples.
• These extensions would also need to be used for similar purposes in Kibana, which has path variations with space identifiers and a different set of required roles and privileges, so the implementation must not be too Elasticsearch-specific. That is to say, we should likely just use strings instead of assuming a limited set of allowable properties or types.
• The roll-out of this change will need to be aligned with the addition of support for these new extensions in our publishing site.