External links in the openAPI output

[lcawl]

🚀 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
#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:

1. 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.
2. 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"
          }

[flobernd]

Agreeing to 1.

Regarding 2., let's continue discussing this in #2758 (comment) where we proposed a way to embed different kind of links in the Markdown text.

[lcawl]

I've created #2925 for the first step, so that the unhelpful links aren't included in the OpenAPI output. I still think there's value to having something equivalent to @doc_id (the URLs would ideally be pulled from the same table.csv) but specific to the API docs purposes rather than the client purposes.

[lcawl]

I've created #3028 to implement a separate @ext_doc_id that we can use to explicitly add externalDocs to the OpenAPI documents. I would also like to update the table.csv file so that there's an (optional?) third value that can be used as the description value per https://spec.openapis.org/oas/v3.0.3#external-documentation-object. However I think that's okay to add in a follow-on PR.