search

go-vela / community

Community Information for Vela (Target's official Pipeline Automation Framework)
https://go-vela.github.io/docs/
Apache License 2.0
22 stars 3 forks source link

server: implement OpenAPI 3.0 #959

Open plyr4 opened 6 months ago

plyr4 commented 6 months ago

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 commented 5 months ago

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.^1

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.