[DOCS]: Clarify GET / response on Serverless

[charlotte-hoblik]

This PR:

• clarifies the response when a user runs GET /
• updates the existing example response
• adds a new example specific to serverless deployments.

On Serverless, this endpoint will always return 8.11.0 as the version number and it is expected. Serverless offers automatic upgrades. Version is no longer something the user manages.

Based on: elastic/docs-content#1960

[github-actions]

Following you can find the validation changes against the target branch for the APIs.

No changes detected.

You can validate these APIs yourself by using the make validate target.

[charlotte-hoblik]

@leemthompo One question: I used the ::: syntax in my changes to highlight notes (screenshot attached). It renders really nicely in the built docs, but I haven’t seen anyone else use it, so I’m not sure if it’s officially supported or just working by coincidence.

Could you let me know if it’s safe to use? I’d prefer to avoid relying on something that might break later.

[leemthompo]

Thanks @charlotte-hoblik! Just suggested a rewording for clarity. On the ::: syntax, I have no idea TBH, I think @flobernd probably knows about this. 😄

I'll let @ppf and @rjernst weigh in on this too

[leemthompo]

@charlotte-hoblik you'll need to run your make generate commands again to make sure the output files are also updated

Would be nice to have screenshots of the examples too for reviewers :)

[leemthompo]

You can also add as much information to the description field as you like to provide context

[ppf2]

++ I see that the most important details are in comment blocks in code today. Let's move that into the description field so that it will actually show up in the API doc details?

  /**
   * The Elasticsearch version number.
   *
   * ::: IMPORTANT: For Serverless deployments, this static value is always `8.11.0` and is used solely for backward compatibility with legacy clients.
   *  Serverless environments are versionless and automatically upgraded, so this value can be safely ignored.
   */

Also, in the description field, I will suggest in addition to noting "safely ignored", it will be helpful to explicitly call out that Serverless are automatically upgraded to the most current version. Thx!

[leemthompo]

The Typescript comments actually are used to generate the OpenAPI documents! But the example yaml files can also have extended descriptions

This is the Elasticsearch api docs workflow schematic:

[leemthompo]

it will be helpful to explicitly call out that Serverless are automatically upgraded to the most current version.

@ppf I wonder if this wording might confuse people into thinking they're running the current/latest stack version?

[ppf2]

True, we can leave it out. I think automatically upgraded already suggests it's upgrading to the latest version that is appropriate for Serverless :D

[charlotte-hoblik]

Thanks for the feedback @leemthompo @ppf2 I’ve added the same clarification to the new Serverless example as well.
Let me know if anything else needs tweaking.

[ppf2]

When the user clicks on the version OBJECT item:

Is it going to show something like the following?

  /**
   * The Elasticsearch version number.
   *
   * ::: IMPORTANT: For Serverless deployments, this static value is always `8.11.0` and is used solely for backward compatibility with legacy clients.
   *  Serverless environments are versionless and automatically upgraded, so this value can be safely ignored.
   */