OpenAPI 3.0 for openapi.yaml?

[woodruffw]

Description

The current openapi.yaml is written as OpenAPI 2.0 (a/k/a Swagger 2.0). There's a newer version (OpenAPI 3.0) that unifies the syntax a bit.

Context: This is part of a yak stack: I'm working on a Python library that will expose Rekor's API types as Python models so that we can easily integrate DSSE types into sigstore-python (sigstore/sigstore-python#628).

I'm using datamodel-codegen to build that model library, which in turn can't use the current OpenAPI spec for Rekor because it requires OpenAPI 3.0.

If there are no objections, then I'm happy to make these changes -- they'll hopefully be pretty small.

[woodruffw]

CC @bobcallaway and @haydentherapper (sorry if you're the wrong people to ping!)

[bobcallaway]

The go-swagger codegen we use doesn't support it. If the changes are backward compatible, we'd be open to it.

[woodruffw]

Yeah, just found go-swagger/go-swagger#1122. Oh well.

I spent a bit of time trying to mold the current OpenAPI definition into a 3.0 form, so I'll push that up as a draft PR. But as you note this probably isn't workable, so I'll find another path forwards on the Python side 🙂

[haydentherapper]

Something else to explore is rebooting the effort to create a gRPC API (#771). We decided to hold off until a 2.0 API, but if there's interest now, we could take a look at shaping it based on the current API.

[woodruffw]

Something else to explore is rebooting the effort to create a gRPC API (#771). We decided to hold off until a 2.0 API, but if there's interest now, we could take a look at shaping it based on the current API.

I think this would also solve my problem, based on my (maybe wrong?) understanding of gRPC: under gRPC, there'd be a set of protobuf definitions that I could generate Python models from, right?

---

Separately: it turns out that there is a public, official Swagger 2.0 to OpenAPI 3.0 REST API: https://converter.swagger.io/#/Converter/convertByUrl. I threw the current Rekor OpenAPI spec into that and it appeared to work; I'll see if it works for my use case.

[haydentherapper]

I think this would also solve my problem, based on my (maybe wrong?) understanding of gRPC: under gRPC, there'd be a set of protobuf definitions that I could generate Python models from, right?

Correct! You could play around with calling Fulcio's gRPC API if you wanted to see how that worked.

[woodruffw]

For visibility: here's the set of hacks I ultimately needed: https://github.com/trailofbits/sigstore-rekor-types/blob/main/codegen/codegen.sh