feat: review resulting OpenAPI specification for best practices

[lrstanley]

Refs:

• https://learn.openapis.org/best-practices.html#describing-large-apis
• https://tyk.io/blog/10-essentials-when-creating-an-open-api-specification/

[lrstanley]

Existing integration tests now use libopenapi-validator, and to some extent, doctor is used more frequently.