Update Cat API query descriptions.

[Naarcha-AWS]

Updates the the query parameter descriptions for three APIs, Cat Aliases, Cat Allocation, and Cat Cluster Manager.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[github-actions]

Changes Analysis

Commit SHA: 24682f0
Comparing To SHA: 01f222e

API Changes

Summary

└─┬Paths
  ├─┬/_cat/allocation
  │ └─┬GET
  │   ├─┬Parameters
  │   │ ├──[🔀] description (15342:20)
  │   │ └─┬Schema
  │   │   └──[🔀] description (15345:22)
  │   ├─┬Parameters
  │   │ ├──[🔀] description (15360:20)
  │   │ └─┬Schema
  │   │   └──[🔀] description (15364:22)
  │   ├─┬Parameters
  │   │ ├──[🔀] description (15368:20)
  │   │ └─┬Schema
  │   │   └──[🔀] description (15372:22)
  │   ├─┬Parameters
  │   │ ├──[🔀] description (15385:20)
  │   │ └─┬Schema
  │   │   └──[🔀] description (15391:22)
  │   ├─┬Parameters
  │   │ ├──[🔀] description (15349:20)
  │   │ └─┬Schema
  │   │   └──[🔀] description (15355:22)
  │   ├─┬Parameters
  │   │ └──[🔀] description (15335:20)
  │   ├─┬Parameters
  │   │ └──[🔀] description (15376:20)
  │   ├─┬Parameters
  │   │ ├──[🔀] description (15396:20)
  │   │ └─┬Schema
  │   │   └──[🔀] description (15400:22)
  │   └─┬Parameters
  │     └──[🔀] description (15328:20)
  ├─┬/_cat/aliases
  │ └─┬GET
  │   ├─┬Parameters
  │   │ ├──[🔀] description (15250:20)
  │   │ └─┬Schema
  │   │   └──[🔀] description (15256:22)
  │   ├─┬Parameters
  │   │ ├──[🔀] description (15261:20)
  │   │ └─┬Schema
  │   │   └──[🔀] description (15265:22)
  │   ├─┬Parameters
  │   │ ├──[🔀] description (15234:20)
  │   │ └─┬Schema
  │   │   └──[🔀] description (15236:22)
  │   ├─┬Parameters
  │   │ ├──[🔀] description (15242:20)
  │   │ └─┬Schema
  │   │   └──[🔀] description (15246:22)
  │   ├─┬Parameters
  │   │ ├──[🔀] description (15223:20)
  │   │ └─┬Schema
  │   │   └──[🔀] description (15229:22)
  │   ├─┬Parameters
  │   │ └──[🔀] description (15209:20)
  │   └─┬Parameters
  │     ├──[🔀] description (15216:20)
  │     └─┬Schema
  │       └──[🔀] description (15219:22)
  ├─┬/_cat/aliases/{name}
  │ └─┬GET
  │   ├─┬Parameters
  │   │ ├──[🔀] description (15242:20)
  │   │ └─┬Schema
  │   │   └──[🔀] description (15246:22)
  │   ├─┬Parameters
  │   │ ├──[🔀] description (15250:20)
  │   │ └─┬Schema
  │   │   └──[🔀] description (15256:22)
  │   ├─┬Parameters
  │   │ ├──[🔀] description (15261:20)
  │   │ └─┬Schema
  │   │   └──[🔀] description (15265:22)
  │   ├─┬Parameters
  │   │ ├──[🔀] description (15223:20)
  │   │ └─┬Schema
  │   │   └──[🔀] description (15229:22)
  │   ├─┬Parameters
  │   │ ├──[🔀] description (15234:20)
  │   │ └─┬Schema
  │   │   └──[🔀] description (15236:22)
  │   ├─┬Parameters
  │   │ └──[🔀] description (15209:20)
  │   └─┬Parameters
  │     ├──[🔀] description (15216:20)
  │     └─┬Schema
  │       └──[🔀] description (15219:22)
  ├─┬/_cat/cluster_manager
  │ └─┬GET
  │   ├─┬Parameters
  │   │ └──[🔀] description (15404:20)
  │   ├─┬Parameters
  │   │ ├──[🔀] description (15411:20)
  │   │ └─┬Schema
  │   │   └──[🔀] description (15414:22)
  │   ├─┬Parameters
  │   │ ├──[🔀] description (15454:20)
  │   │ └─┬Schema
  │   │   └──[🔀] description (15460:22)
  │   ├─┬Parameters
  │   │ ├──[🔀] description (15465:20)
  │   │ └─┬Schema
  │   │   └──[🔀] description (15469:22)
  │   ├─┬Parameters
  │   │ ├──[🔀] description (15418:20)
  │   │ └─┬Schema
  │   │   └──[🔀] description (15424:22)
  │   └─┬Parameters
  │     └──[🔀] description (15445:20)
  └─┬/_cat/allocation/{node_id}
    └─┬GET
      ├─┬Parameters
      │ ├──[🔀] description (15360:20)
      │ └─┬Schema
      │   └──[🔀] description (15364:22)
      ├─┬Parameters
      │ ├──[🔀] description (15385:20)
      │ └─┬Schema
      │   └──[🔀] description (15391:22)
      ├─┬Parameters
      │ └──[🔀] description (15376:20)
      ├─┬Parameters
      │ ├──[🔀] description (15342:20)
      │ └─┬Schema
      │   └──[🔀] description (15345:22)
      ├─┬Parameters
      │ ├──[🔀] description (15368:20)
      │ └─┬Schema
      │   └──[🔀] description (15372:22)
      ├─┬Parameters
      │ ├──[🔀] description (15396:20)
      │ └─┬Schema
      │   └──[🔀] description (15400:22)
      ├─┬Parameters
      │ └──[🔀] description (15320:20)
      ├─┬Parameters
      │ └──[🔀] description (15335:20)
      ├─┬Parameters
      │ └──[🔀] description (15328:20)
      └─┬Parameters
        ├──[🔀] description (15349:20)
        └─┬Schema
          └──[🔀] description (15355:22)

Document Element	Total Changes	Breaking Changes
paths	67	0

• Total Changes: 67
• Modifications: 67

Report

The full API changes report is available at: https://github.com/opensearch-project/opensearch-api-specification/actions/runs/12283607679/artifacts/2307876719

API Coverage

	Before	After	Δ
Covered (%)	606 (59.35 %)	606 (59.35 %)	0 (0 %)
Uncovered (%)	415 (40.65 %)	415 (40.65 %)	0 (0 %)
Unknown	43	43	0

[github-actions]

Spec Test Coverage Analysis

Total	Tested
536	475 (88.62 %)

[kolchfa-aws]

Please apply changes globally to all instances of the same descriptions. Made suggestions in opensearch-project/documentation-website#8930. cc: @natebower

[dblock]

Note that it's possible to consolidate schema and use $ref if something is repeated all over the place. We could make common parameters for cat APIs for example.

[Naarcha-AWS]

Note that it's possible to consolidate schema and use $ref if something is repeated all over the place. We could make common parameters for cat APIs for example.

Is that something we should do now or flag it for later? For the time being, we could do a simple find and replace to make the descriptions consistent.

[kolchfa-aws]

$ref is definitely the preferred long-term strategy.

[dblock]

Is that something we should do now or flag it for later? For the time being, we could do a simple find and replace to make the descriptions consistent.

It's really up to you. I would try to consolidate those into $refs if you're going to do a lot of replacing.

[dblock]

Can I merge this?

[Naarcha-AWS]

Lets go ahead and merge this one. I'll address the refs in a separate PR.