[OpenAPI] Automatically generate the list of tags

[lcawl]

Priority: med
Effort: low?

Relates to #2310

🚀 Feature Proposal

The OpenAPI documents should contain root-level list of all the tags that are used in the document.
The kbn-openapi-bundler generates this list of tags sorted alphabetically so it would be nice to have a similar feature for Elasticsearch.

There is a complexity around the x-displayName associated with the tag, which should affect the sort order but is not currently known in the specification. So this might require us to have that mapping between tag name and displayName stored somewhere in the spec too.

Motivation

Per https://spec.openapis.org/oas/v3.0.3#fixed-fields, it's "A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools...".

Per https://docs.bump.sh/help/customization-options/operations-navigation/#group-operations-by-tag, since we've chosen to group our operations by tag, "Bump.sh will use the tags from your API definition to group, name and sort operations... When “Group operations by tag” is selected, operations without tags will be ignored and won’t be displayed".

Thus there are implications where content could be missing or poorly organized if tags are missing from the individual specs or from the list of all tags.

Example

Currently we're addressing this need by using an overlay: https://github.com/elastic/elasticsearch-specification/blob/main/docs/overlays/elasticsearch-shared-overlays.yaml

For example:

  - target: '$'
    description: Add document-level tags sorted by display name
    update:
      tags:
      # A
        - name: autoscaling
          x-displayName: Autoscaling
      # B
        - name: analytics
          x-displayName: Behavioral analytics
      # C 
        - name: cat
          x-displayName: Compact and aligned text (CAT)
          description: >
            The compact and aligned text (CAT) APIs aim are intended only for human consumption using the Kibana console or command line.
            They are not intended for use by applications...

We've also added a linting rule to indicate when an operation-level tag is missing from the document-level list, however it would be nice to not have to maintain that list manually in the overlay.