Expose OpenAPI spec on HTTP API server

[cretz]

trafficstars

Describe the solution you'd like

Need OpenAPI spec on HTTP API endpoint. Need to investigate/understand the following:

• Probably needs to be generated on the api-go repo and exposed as a go:embed for all to use including this repo
• Unsure whether OpenAPI v2 and/or v3 needs to be made available (generator for former at https://github.com/grpc-ecosystem/grpc-gateway/tree/main/protoc-gen-openapiv2, latter on https://github.com/google/gnostic/tree/main/cmd/protoc-gen-openapi)
• Clarify that these are experimental until we are happy with them, because changing a spec can be backwards incompatible
• OpenAPI v2 generator prefixes v1 to all definition names which is ugly
• Enums have to be altered to support our incredibly unfortunate enum-to-string formatting today
• Needs support for shorthand payloads
• Need to make sure the endpoint we serve at (e.g. openapi.json) is industry accepted one

[tdeebswihart]

Enums have to be altered to support our incredibly unfortunate enum-to-string formatting today

Chad and I have discussed this already, but with v1.23 of server this wont be necessary

[shedokan]

Is this complete or was it closed?

If complete, can you please link the docs or explain how to see them?