Cert authority, host factory, policies, public keys, roles, and resources spec documents are reviewed

[izgeri]

Please review the following, with the goal of identifying anything that could be defined more clearly or organized better. We already have automation to verify the technical details of the spec; we mainly want to ensure the human-readable parts make sense and that there is nothing surprising / nothing that stands out as odd or missing in the spec definition.

In openapi.yml:

• Review the tags and how the paths are organized by tag to make sure the groupings are sensible in openapi.yml
• Review the ref names for the paths in openapi.yml to make sure the referenced component path makes sense for each endpoint
• Review the schemas in openapi.yml to make sure their definitions are correct and the descriptions are clear
• Review the responses in openapi.yml - are there any missing that you are surprised are not there?

In each of the files cert-auth.yml, host-factory.yml, policies.yml, public-keys.yml, roles.yml, and resources.yml:

• Review the summary and description for each path to make sure the descriptions are clear and correct
• Review the operationId for each path to ensure it makes sense - these will become client methods
• Review the parameters for each path - is anything surprising?
• Review the responses for each path - is anything surprising?
• Do you know of any recent changes to the endpoints in this file that should be reflected in the spec but aren’t yet?

Please open up a PR for any minor tweaks you’d like to propose, but otherwise feel free to list suggested changes as a comment in this issue.