Investigate creating an OpenAPI spec
What we're after
It would be useful to have an OpenAPI spec for the API of the billing service.
Hypothesized benefit(s)/why:
- The first use case is that the cybersecurity team could load it into OWASP ZAP to accurately scan the API. (It is more challenging to spider an API than a webpage, as we've typically done with ZAP.)
Security considerations
No additional risk, as API code is already open source.
Notes for implementers
- Similar to how sqlc allows us to write SQL and generate Go types and functions, oapi-codegen takes an OpenAPI spec as input and generates a Go HTTP API. It can generate code for a variety of router packages, including Chi.
- Requirement: We must be able to wrap the generated endpoints in middleware, like the JWT/scope middleware.
- Alternative approaches sound less good to me. Generating a spec from the Go might not be possible at all, and generating both the API and the spec from an intermediate Go representation sounds more complicated. (I saw another library that works that way, and does so at runtime, which is likely slower than compile-time codegen.)
Related issues/sub-projects
These issues expand the API. This issue is a prereq for them.