executable interface to openapi document validation

[karenetheridge]

Create a shell-executable wrapper that loads an openapi document from json or yaml and provides information about the data therein.

• validation: if the document is invalid, clearly state what the errors are
• information: (assuming the document is valid), dump information like:
  • number of paths, webhooks, other high level objects
  • number of operations under paths, webhooks
  • linting items, that are not strictly "wrong" but might lead to issues at runtime:
    • any unresolved $refs (that point to external documents): identify the uri(s) of these external refs
    • $refs that point to the wrong entity type
    • missing path parameter definitions
    • ...

Also we can do some static analysis to try to predict some runtime issues, e.g. unresolved $refs that would point to this internal document (therefore they obviously can never resolve).