server: implement OpenAPI 3.0

[plyr4]

Description

Vela currently uses Swagger, but should consider migrating to OpenAPI 3.0 at some point.

It would require server and worker changes, to code and CI, processes, docs likely too. More work than I'd like to do but it may be worth it in the long run.

Swagger 3.1.0 supports OAS 3.*.* so it might not be that bad https://swagger.io/specification/

Why?

Future-proofing, mostly, getting with the times.

[wass3r]

just to clarify, since it's a bit confusing. we are currently producing Swagger 2.0 specs (via https://github.com/go-swagger/go-swagger - it only supports 2.0). Swagger 2.0 is the predecessor of OpenAPI 3.x.

OpenAPI extends the capabilities of its predecessor, Swagger, by offering a more comprehensive and standardized approach to API description.¹²

it's confusing because Swagger is also the name of a software framework and API tools.

there's definitely some overlap in terms of compatibility between the two, but i think we'd have to ditch our current tool and look for something else, which might not rely on marking up code the way we do today.

Footnotes

1. https://apidog.com/blog/swagger-vs-openapi/ ↩

2. https://blog.postman.com/openapi-vs-swagger/ ↩