Openapi: adding privileges

[l-trotta]

Closes #4303.

There was no desired output in the original issue, so I'm not sure if this is the format expected. Let me know and I'll change it!

[l-trotta]

validation failing because this adds a new field to the openapi output, will be fixed in case that's how we want to add the information

[lcawl]

My two cents is that of the three options I mentioned in #4303 (comment), "an addendum tacked onto the beginning or end of the operation's "description" field" is likely the best current option since it aligns with what Kibana's doing. Otherwise I think if we went the extension route we'd need a more open-ended structure since the privileges in the Kibana and Cloud API docs would need different options than "cluster-privileges" and "index-privileges".

[georgewallace]

Coming into this one a little late but I do agree with @lcawl if we already have a team doing this a different way then we should follow suit to stay consistent. I do think long term keeping these as separate fields makes the most sense though. @lcawl is this what you are talking about?

[l-trotta]

@lcawl @georgewallace updated so that privileges are now in the description! please help me with the output format because I'm really not a fan of this one ^^"

[georgewallace]

@lcawl curious your thoughts but if we follow suite with what Kibana is doing would be something like

[Required authorization] index-privilege: monitor, cluster-privilege: monitor

[lcawl]

Could we format it into more complete phrases? For example:

## Required authorization

 * Index privileges: `blah`, `blah`, `blah`
 * Cluster privileges: `blah`

Or if there's concern about including markdown, then maybe:

Required authorization includes: `blah`, `blah`, `blah` index privileges and `blah` cluster privileges.

[georgewallace]

@lcawl I like the first one. It doesnt necessarily match with what Kibana is doing (Get an agent action status) but I think that is ok as your first one likes much better. The Operation summary name is already an H2, for this sake should it be an h3 instead? I see inconsistencies on the pages now so H2 should be fine but just in case.

[swallez]

Left some code-improvement suggestions.

[swallez]

LGTM

[github-actions]

The backport to 9.0 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-9.0 9.0
# Navigate to the new working tree
cd .worktrees/backport-9.0
# Create a new branch
git switch --create backport-4434-to-9.0
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 509616749de15d76a72c4ae8937c7faaeb34292d
# Push it to GitHub
git push --set-upstream origin backport-4434-to-9.0
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-9.0

Then, create a pull request where the base branch is 9.0 and the compare/head branch is backport-4434-to-9.0.

[github-actions]

The backport to 8.19 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-8.19 8.19
# Navigate to the new working tree
cd .worktrees/backport-8.19
# Create a new branch
git switch --create backport-4434-to-8.19
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 509616749de15d76a72c4ae8937c7faaeb34292d
# Push it to GitHub
git push --set-upstream origin backport-4434-to-8.19
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-8.19

Then, create a pull request where the base branch is 8.19 and the compare/head branch is backport-4434-to-8.19.

[github-actions]

The backport to 8.18 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-8.18 8.18
# Navigate to the new working tree
cd .worktrees/backport-8.18
# Create a new branch
git switch --create backport-4434-to-8.18
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 509616749de15d76a72c4ae8937c7faaeb34292d
# Push it to GitHub
git push --set-upstream origin backport-4434-to-8.18
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-8.18

Then, create a pull request where the base branch is 8.18 and the compare/head branch is backport-4434-to-8.18.