Unique summaries per path

[lcawl]

🚀 Feature Proposal

Have a maximum of one specification per unique path.
Alternatively, have a method for specifying a unique operation summary for each unique path so that this information can be used in the OpenAPI document output.

NOTE: This might eventually overlap with a desire for something like x-tagGroups, where we could group similar endpoints and affect the navigation such that tags have a hierarchy. That's not yet supported in our publishing system, however.

Motivation

Currently we can have multiple paths represented in a single specification, for example:

https://github.com./elastic/elasticsearch-specification/blob/main/specification/nodes/stats/NodesStatsRequest.ts

 urls: [
    {
      path: '/_nodes/stats'
      methods: ['GET']
    },
    {
      path: '/_nodes/{node_id}/stats'
      methods: ['GET']
    },
    {
      path: '/_nodes/stats/{metric}'
      methods: ['GET']
    },
    {
      path: '/_nodes/{node_id}/stats/{metric}'
      methods: ['GET']
    },
    {
      path: '/_nodes/stats/{metric}/{index_metric}'
      methods: ['GET']
    },
    {
      path: '/_nodes/{node_id}/stats/{metric}/{index_metric}'
      methods: ['GET']
    }
  ]

Since they're all covered in a single specification, they all share the same operation summary and description in the OpenAPI output, which makes it harder to tell which one to use:

Example

Since we only had a single page in the old docs for content like this (e.g. https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-stats.html) we don't have an example that shows how the description should vary, but the work required to explain those difference is worth the effort IMO.

[DaveCTurner]

we don't have an example

I encountered this issue too and can provide an example: the get snapshot status API has a summary which mentions the {repository} and {snapshot} parameters which makes no sense in the docs for GET /_snapshot/_status which has neither parameter. With separate summaries for each pattern we can make it much clearer that GET /_snapshot/_status yields only the currently running snapshots, GET /_snapshot/{repository}/_status yields only the currently running snapshots in that repository, and GET /_snapshot/{repository}/{snapshot}/_status looks up the specified snapshots.

[sophiec20]

Also relevant for several of the ML APIs (not just datafeed preview).

GET /_ml/datafeeds/{datafeed_id}/_preview
POST /_ml/datafeeds/{datafeed_id}/_preview
GET /_ml/datafeeds/_preview
POST /_ml/datafeeds/_preview

With the added complication that is includes {xxx_id} param and supports both POST and GET.

This was represented as a single page in old docs. https://www.elastic.co/guide/en/elasticsearch/reference/8.18/ml-preview-datafeed.html

[lcawl]

@swallez If we have to continue publishing all variations of the paths from a single specification file and want to have some way of defining unique operation summaries at a minimum, could it perhaps be accomplished in the specifications like this?:

 urls: [
    {
      path: '/_nodes/stats'
      methods: ['GET']
      summary: "Get all stats for all nodes"
    },
    {
      path: '/_nodes/{node_id}/stats'
      methods: ['GET']
      summary: "Get all stats for a node"
    },
    ...

... or whatever text makes it easier for folks to skim and understand the differences