Add additional technical writer feedback to Cluster APIs

[Naarcha-AWS]

This PR adds descriptions for certain enums and array options that exist for Cluster APIs. Also adds defaults where they might not exist, and makes some descriptions more descriptive.

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: 1b9f37c
Comparing To SHA: 5ed668d

API Changes

Summary

├─┬Paths
│ ├─┬/_cluster/health
│ │ └─┬GET
│ │   ├─┬Parameters
│ │   │ └──[➕] description (18289:20)
│ │   ├──Parameters
│ │   ├─┬Parameters
│ │   │ └──[➕] description (18327:20)
│ │   └─┬Parameters
│ │     └─┬Schema
│ │       └──[➕] default (18358:18)❌ 
│ ├─┬/_cluster/settings
│ │ ├─┬GET
│ │ │ └─┬Parameters
│ │ │   └──[➕] description (18228:20)
│ │ └─┬PUT
│ │   └─┬Parameters
│ │     └──[➕] description (18491:20)
│ ├─┬/_cluster/state
│ │ └─┬GET
│ │   └─┬Parameters
│ │     └──[➕] description (18607:20)
│ ├─┬/_cluster/allocation/explain
│ │ ├─┬GET
│ │ │ └─┬Parameters
│ │ │   └──[🔀] description (18084:20)
│ │ └─┬POST
│ │   └─┬Parameters
│ │     └──[🔀] description (18084:20)
│ ├─┬/_component_template/{name}
│ │ ├─┬GET
│ │ │ ├─┬Parameters
│ │ │ │ └──[➕] description (18183:20)
│ │ │ └─┬Parameters
│ │ │   └──[🔀] description (18192:20)
│ │ ├─┬PUT
│ │ │ └─┬Parameters
│ │ │   └──[➕] description (18446:20)
│ │ ├─┬POST
│ │ │ └─┬Parameters
│ │ │   └──[➕] description (18446:20)
│ │ ├─┬DELETE
│ │ │ └─┬Parameters
│ │ │   └──[🔀] description (18102:20)
│ │ └─┬HEAD
│ │   └─┬Parameters
│ │     └──[➕] description (18147:20)
│ ├─┬/_cluster/state/{metric}
│ │ └─┬GET
│ │   └─┬Parameters
│ │     └──[➕] description (18607:20)
│ ├─┬/_cluster/decommission/awareness/{awareness_attribute_name}/{awareness_attribute_value}
│ │ └─┬PUT
│ │   └─┬Parameters
│ │     ├──[🔀] description (18484:20)
│ │     └─┬Schema
│ │       └──[🔀] description (18487:22)
│ ├─┬/_component_template
│ │ └─┬GET
│ │   ├─┬Parameters
│ │   │ └──[➕] description (18183:20)
│ │   └─┬Parameters
│ │     └──[🔀] description (18192:20)
│ ├─┬/_cluster/routing/awareness/{attribute}/weights
│ │ └─┬PUT
│ │   └─┬Parameters
│ │     ├──[🔀] description (18522:20)
│ │     └─┬Schema
│ │       └──[🔀] description (18525:22)
│ ├─┬/_cluster/health/{index}
│ │ └─┬GET
│ │   ├─┬Parameters
│ │   │ └──[➕] description (18289:20)
│ │   ├─┬Parameters
│ │   │ └─┬Schema
│ │   │   └──[➕] default (18358:18)❌ 
│ │   ├──Parameters
│ │   └─┬Parameters
│ │     └──[➕] description (18327:20)
│ ├─┬/_cluster/pending_tasks
│ │ └─┬GET
│ │   └─┬Parameters
│ │     └──[➕] description (18378:20)
│ ├─┬/_cluster/state/{metric}/{index}
│ │ └─┬GET
│ │   └─┬Parameters
│ │     └──[➕] description (18607:20)
│ └─┬/_cluster/reroute
│   └─┬POST
│     ├─┬Parameters
│     │ └──[➕] description (18530:20)
│     └─┬Parameters
│       └──[🔀] description (18544:20)
└─┬Components
  ├─┬_common___WaitForEvents
  │ ├──[➖] enum (36768:11)❌ 
  │ ├──[➖] enum (36769:11)❌ 
  │ ├──[➖] enum (36770:11)❌ 
  │ ├──[➖] enum (36771:11)❌ 
  │ ├──[➖] enum (36772:11)❌ 
  │ ├──[➖] enum (36773:11)❌ 
  │ ├──[➖] type (36766:13)❌ 
  │ ├──[➕] oneOf (36783:11)
  │ ├──[➕] oneOf (36786:11)
  │ ├──[➕] oneOf (36789:11)
  │ ├──[➕] oneOf (36792:11)
  │ ├──[➕] oneOf (36795:11)
  │ └──[➕] oneOf (36798:11)
  └─┬cluster.reroute___Metric
    ├──[➖] enum (50838:11)❌ 
    ├──[➖] enum (50840:11)❌ 
    ├──[➖] enum (50841:11)❌ 
    ├──[➖] enum (50844:11)❌ 
    ├──[➖] enum (50846:11)❌ 
    ├──[➖] enum (50839:11)❌ 
    ├──[➖] enum (50842:11)❌ 
    ├──[➖] enum (50843:11)❌ 
    ├──[➖] enum (50845:11)❌ 
    ├──[➖] type (50836:13)❌ 
    ├──[➕] oneOf (50864:11)
    ├──[➕] oneOf (50867:11)
    ├──[➕] oneOf (50870:11)
    ├──[➕] oneOf (50873:11)
    ├──[➕] oneOf (50876:11)
    ├──[➕] oneOf (50879:11)
    ├──[➕] oneOf (50882:11)
    ├──[➕] oneOf (50885:11)
    └──[➕] oneOf (50888:11)

Document Element	Total Changes	Breaking Changes
paths	28	2
components	32	17

• ❌ BREAKING Changes: 19 out of 60
• Modifications: 10
• Removals: 17
• Additions: 33
• Breaking Removals: 17
• Breaking Additions: 2

Report

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

API Coverage

	Before	After	Δ
Covered (%)	663 (64.94 %)	663 (64.94 %)	0 (0 %)
Uncovered (%)	358 (35.06 %)	358 (35.06 %)	0 (0 %)
Unknown	45	45	0

[github-actions]

Spec Test Coverage Analysis

Total	Tested
595	593 (99.66 %)

[Naarcha-AWS]

Adding Missing Defaults and changing enums to OneOf are not breaking changes, since the enums already existed as strings and the missing default already exists. Let me know if I need to tweak anything else though.

[Naarcha-AWS]

All checks are passing.

[nhtruong]

The spec is being used by different applications, like codegen to generate api methods for different OpenSearch clients. So having something that's only usable on the docs website like {{site.url}}{{site.baseurl}} is not good. We already have the ability replace https://opensearch.org/docs/latest with {{site.url}}{{site.baseurl}} in the docs tooling here: https://github.com/opensearch-project/documentation-website/blob/main/spec-insert/config.yml#L11

[nhtruong]

Same issue as above.

[nhtruong]

I've looked into the Vale error. Looks like a bug on Vale's end. I've created an issue on their repo here.

[nhtruong]

This PR will handle the Vale failure