When OpenAPI 3.0 is officially released and tooling available to support it, we should migrate the api spec to it. Needed to implement #2
