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

[swallez]

The questions is: do we have to continue publishing all variations? I did an experiment where there's one OpenAPI operation per API endpoint, that has the path with the full set of parameters (so that bump.sh isn't confused with having path parameters that aren't part of the path templates), and added alternate path templates at the top of the description.

The result looks like below. Would that be acceptable? This brings us to something very close to the old docs, with one single page per endpoint with its different variations.

Note though that it doesn't prevent having the summary you suggested, as a specific explanation of each path variation.

[lcawl]

The questions is: do we have to continue publishing all variations? I did an experiment where there's one OpenAPI operation per API endpoint, that has the path with the full set of parameters... Would that be acceptable?

IMO unless we get feedback from a lot of users otherwise, it's okay from a docs point of view to have those variations appear only in the description for a single operation. We'd just need to ensure the description includes advice about why you'd use one over the other and how/if their request and response bodies (if applicable) differ. Since OpenAPI currently insists that all path parameters are required, we'd also ideally mention in those parameter descriptions what happens if you omit them (e.g. if node_id is omitted, info is returned for all nodes, etc). However, if there are teams that are using the OpenAPI documents as the source for things like terraform resources or console help, they'd also be impacted by this abbreviation.

cc @szabosteve and @georgewallace in case you want to weigh in

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.

Yes, from a docs point of view, having complete specifications (and in particular, unique summaries and descriptions) for each path is the most accurate.