[DISCUSS] Consolidating generated API docs for Serverless and Stateful

[szabosteve]

Description

Currently, we maintain two separate generated documentation sets for Elasticsearch APIs: one for stateful and another for serverless. Both sets are generated from the same specification, with no differences in the underlying source files. This duplication can be confusing, for example, when an example works in one context but not in the other.

Historically, the split was based on the assumption that stateful and serverless APIs would diverge quickly and significantly. Today, it seems that the differences are much smaller than we expected.

To reduce complexity and mitigate the problems that the two sets cause, we should reconsider consolidating these into a single API documentation set that serves both serverless and stateful environments.

[lcawl]

I think the main complexity would be around ensuring that the way the differences are called out is as close as possible to the way we've addressed this issue in narrative docs (via applies_to) so our readers don't get confused between the two sets of docs. That is to say, we'd want to ensure that x-state behaviour matches expectations. For example, if x-state is declared at the API/operation-level, it means all parameters and properties share that availability unless otherwise specified. It might be a good idea to try mocking up a simple OpenAPI document that uses x-state this way to see if there are things we'll need to fix before we try getting this working in the generator.