Document APIs with OpenAPI / swagger

[cjllanwarne]

Description

Today our APIs are "documented" only through the list of endpoint handlers in implementation code (example).

We can and should:

• Create OpenAPI documentation for our APIs (maybe per-service, maybe once in the gateway?)
• Host swagger page/pages for exploring and testing out APIs

Security Impact

High

Security Impact Description

"None" for the creation of documentation, since we do not believe that documenting our APIs is inherently risky.

"High" for hosting a new functional component on our web endpoints. Mitigating factor: swagger pages are loaded as static html with no need (or ability) to interact with other functional components, except through the same public APIs as are already accessible.

Appsec Signoff

• Reviewed and approved