External links in the openAPI output

🚀 Feature Proposal

IMO we need to potentially change the handing of the docId and docURL in the OpenAPI generator (or split off a separate modifier for API docs purposes and leave the others for client purposes).

Motivation

There are currently docUrl and docId properties in the specification, which in the OpenAPI output are included as externalDocs. However, per the comments in https://github.com/elastic/elasticsearch-specification/issues/714, those properties are used by the clients to link to the documentation and so don't serve the need to link from the documentation to some other site. From a docs point of view, it's essentially a circular, self-referential link.

My proposal is therefore:

Cease including the docURL and docID values in the OpenAPI output, since they're used for client-specific purposes and those purposes don't align with documentation needs.
Add a new externalDocs or some such property to the specifications to enable us to explicitly add external links to the openAPI output.

Or, if the clients do not use those docURL and docID values, the solution might be to just stop filling them in automatically (presumably from the rest spec files). Then they could be set explicitly to a useful value when needed.

NOTE: Bump.sh, which we use to publish our API documentation, currently doesn't support externalDocs, so that is being pursued as an enhancement request.

Example

I didn't see any examples where the docId or docURL were explicitly added to the specs, but I see them in the output/schema, for example:

      "docId": "async-search",
      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/async-search.html",
      "name": "async_search.delete",
      "request": {
        "name": "Request",
        "namespace": "async_search.delete"
      },

... which then generates the following OpenAPI output:

     "delete": {
        "tags": [
          "async_search.delete"
        ],
        "externalDocs": {
          "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/async-search.html"
        },
        "operationId": "async-search-delete",

It seems to me the proposed new property could be implemented the same way (except with the optional inclusion of a description) and ultimately output in the OpenAPI document like this:

..
"paths": {
    "/_async_search/{id}": {
      "get": {
        "tags": [
          "async_search.get"
          "externalDocs": {
            "description": "Introduction to asynchronous search",
            "url": "https://example.com"
          }

elastic / elasticsearch-specification