Add possible mode values to put /_admin/cluster/maintenance/<server-id>

[aMahanna]

Description

Added a sentence to save users an extra click/search for its documentation page

The Rest API description for this endpoint (in the Web UI) doesn't specify the possible mode values:

Whereas a similar endpoint (PUT /_admin/cluster/maintenance) does indeed specify possible values for mode:

I'm aware that the possible values are also present under the Schema section in the Request Body header so feel free to close this PR if that is deemed sufficient

Upstream PRs

• 3.10:
• 3.11:
• 3.12:

[arangodb-docs-automation]

Deploy Preview Available Via
https://deploy-preview-406--docs-hugo.netlify.app

[Simran-B]

Not a fan of having this information also in the free-text description if we already have it documented in a structured form - it's likely that the two drift apart if we ever add or rename modes. I think we should check first whether we can improve the request body description by using an OpenAPI enum. Not sure if Swagger-UI meanwhile displays something like this nicely (e.g. a dropdown menu with the two options)

[aMahanna]

makes senses! closing 👍

[Simran-B]

@aMahanna Revisiting this issue, I found out that there is an option in Swagger-UI to show the Schema instead of the Example Value by default:

However, there is a problem: If no schema defined (which is unfortunately the case for many request and especially response descriptions), it still tries to select the non-existing Schema tab and then displays an error:

I can check whether this has been fixed in the latest Swagger-UI version. In the latest code, it actually looks like they check whether the tab exists before trying to activate it. I think the Schema tab is generally more useful than the Example Value tab, also because it often falls back to values like 0, false and "string" that aren't actually valid or nonsense. This would make it easier to discover the descriptions of the parameters. If you click the Try it out button, it automatically changes to a textarea still, revealing the example values.

[Simran-B]

It has indeed been fixed:

PR to upgrade Swagger-UI: arangodb/arangodb#21685