Upgrade to OpenAPI v3

[michaeladler]

Description

• [x] Migrate our spec from Swagger to OpenAPI v3
• [x] Adapt the code generation process to use the newly upgraded spec (go-openapi doesn't support OpenAPI v3)

Motivation

Upgrading from Swagger to OpenAPI v3 offers numerous benefits, including enhanced specification features, better support for modern use cases, improved developer experience, access to a richer ecosystem and tooling, future-proofing our API specifications, and ensuring compliance and interoperability. These advantages make a compelling case for undertaking the upgrade to OpenAPI v3, and we recommend proceeding with this transition to realize these benefits for our project.

Proposed Solution (optional)

These are the candidates for code generation:

• https://github.com/deepmap/oapi-codegen
• https://github.com/ogen-go/ogen

Note that we have a special requirement: the /jobs/events API is streaming (server-sent events). Currently, it is not possible to use ogen for that purpose because it utilizes io.ReadAll under the hood. For more details, see this issue.