priority: low
effort: medium

🚀 Feature Proposal

Add support for custom URL labels in https://github.com/elastic/elasticsearch-specification/blob/main/specification/_doc_ids/table.csv (for example, add a third column that is a text string).
Then when a specification uses one of those IDs in @ext_doc_id, use that string in the description field of the externalDocs object per https://spec.openapis.org/oas/latest.html#external-documentation-object

Currently we have no way of supplying those descriptions, so they all default to "External documentation".

Motivation

We received the following feedback about the current behaviour: "In general, could we consider a better name than “External documentation”? To me it implies leaving Elastic.co and not leaving the serverless API docs. Maybe call it “Elasticsearch Reference Documentation” or something like that."

Example

We currently provide externalDocs links for the tags via overlays, which look like this in the final OpenAPI document:

{
      "name": "connector",
      "x-displayName": "Connector",
      "externalDocs": {
        "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/es-connectors-tutorial-api.html",
        "description": "Check out the connector API tutorial"
      }
    }

You can see that the string is properly displayed by Bump.sh, for example: https://www.elastic.co/docs/api/doc/elasticsearch-serverless/group/endpoint-connector