[OpenAPI] URL resolution is always current instead of branch

[lcawl]

🐛 Bug

The usage of the table.csv file to resolve URLs for @doc_id and @ext_doc_id was implemented in #714 and #2748.

The table supports the use of {branch} as a variable in the URL, for example:

data-stream-lifecycle,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/data-stream-lifecycle.html

However, it seems like that's being resolved to current every time, instead of the appropriate branch. For example, check out #4627 which ought to be linking to https://www.elastic.co/guide/en/elasticsearch/reference/8.18/data-stream-lifecycle.html but the OpenAPI document contains:

        "summary": "Get data stream lifecycles",
        "description": "Get the data stream lifecycle configuration of one or more data streams.",
        "externalDocs": {
          "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/data-stream-lifecycle.html"
        },

Current is inappropriate in this case, since it'll redirect to the V9 docs and therefore lead our users to the wrong site.

Solution

It seems like the problem is related to this code in schema.rs:

pub fn convert_external_docs(&self, obj: &impl clients_schema::ExternalDocument) -> Option<ExternalDocumentation> {
        // FIXME: does the model contain resolved doc_id?
        obj.ext_doc_url().map(|url| {
            let branch: &str = self
                .model
                .info
                .as_ref()
                .and_then(|i| i.version.as_deref())
                .unwrap_or("current");
            ExternalDocumentation {
                description: None,
                url: url.trim().replace("{branch}", branch),
                extensions: Default::default(),
            }
        })
    }

If I hack the schema.json file to explicitly add a version value, like this:

  "_info": {
    "version": "8.18",
...
  },

... then the URLs are correct in the OpenAPI output when I run the make transform-to-openapi command:

        "summary": "Get data stream lifecycles",
        "description": "Get the data stream lifecycle configuration of one or more data streams.",
        "externalDocs": {
          "url": "https://www.elastic.co/guide/en/elasticsearch/reference/8.18/data-stream-lifecycle.html"
        },

I'm not sure how you want to add that version detail to the schema.json but IMO it could either be something that's determined solely by the repo branch or else by a configuration option. The slight problem with using the repo branch is that there's a delay between when a repo branch is created and when the docs are public. For example, in the aforementioned PR:

• 8.18 branch should go to https://www.elastic.co/guide/en/elasticsearch/reference/8.18/data-stream-lifecycle.html
• 8.19 branch should go to https://www.elastic.co/guide/en/elasticsearch/reference/8.x/data-stream-lifecycle.html because https://www.elastic.co/guide/en/elasticsearch/reference/8.19/data-stream-lifecycle.html isn't live yet.

However, since we're not publishing the 8.19 OpenAPI docs until 8.19 is released (at which point the other docs will be live too), maybe that's an unnecessary concern.

The other consideration is that we wouldn't want that schema.json version detail to get populated into the OpenAPI document's info.version, since the version information in an API document is about the version of the file, not about the version of the API per https://spec.openapis.org/oas/latest#info-object. Maybe it's not a big deal right now, but if we get to the point where we have a reason for incrementing the OpenAPI document's version, we wouldn't want that to break the URL resolution functionality.

Thus if it's possible to add the missing version detail to the schema.json file (without pushing that out into the OpenAPI documents) or else derive the URL branches from something other than the schema.json file, that would be great!