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.