use OpenAPI to document endpoints and centralize endpoint specifications

[karenetheridge]

While our route declarations are [probably] too complicated to have them be auto-generated by an OpenAPI plugin (there are various 'under' routes providing preconditions which are carefully stacked atop each other), OpenAPI does provide a mechanism for us to declare information about endpoints such as:

• expected input and output formats
• additional header information expected in requests and provided responses
• limitations such as access privileges required for an endpoint
• deprecation information

As of conch API version 3.0, we do have query parameters and request and response payload formats declared as JSON Schemas, but this information is repeated in a few places such as documentation (which must be manually written) and in the code where an explicit call must be made to verify the format. If we put this information in a well-formed data structure (such as what the OpenAPI specification defines), we can auto-generate documentation, as well as have a centralized hook (run for every endpoint dispatch) that automatically performs payload validation. (Conch API v3.1 plans to add hooks to peform centralized validation, but still relies on our ad-hoc format for defining payload schemas and can still be improved substantially.)

This is blocked on the release of OpenAPI 3.1, which adds a lot more functionality that we want to use, as well as fixes some cross-compatibility issues between the OpenAPI specification and the JSON Schema specification.

It is also blocked on the completion of a JSON Schema evaluator in perl that respects the draft 2019-09 specification (https://json-schema.org/specification.html) -- currently under development.

related to #978.