Create a Buf plugin for protoc-gen-openapi

[hbjydev]

It would be really nice to have a remote plugin uploaded to Buf's BSR for protoc-gen-openapi, so that we can build our OpenAPI 3 schemas from our protobuf schemas using Buf in smaller Docker containers.

The buf.gen.yaml would essentially look like this:

---
version: v1
plugins:
  - remote: buf.build/protocolbuffers/plugins/go:v1.28.1-1
    out: gen/go
    opt:
      - paths=source_relative

  # ...

  - remote: buf.build/gnostic/plugins/protoc-gen-openapi:<version>-<release>
    out: gen/oapi3
    opt:
      - title=OpenAPI v3

Then, we can just run buf generate to spit out all of this stuff from a pretty tiny Docker build step.

FROM bufbuild/buf:1.7.0 AS buf

WORKDIR /src

COPY buf.yaml buf.yaml
COPY buf.gen.yaml buf.gen.yaml
COPY proto/ proto/

RUN buf generate

Like this one.

I'd love to be able to get this one built, it would be a really big help to people like me who are trying to stick to Buf for all their protobuf needs, and using remote plugins reduces the number of required tools to install locally versus using protoc locally, and having to install all the relevant protoc extensions with it.

Thanks! :)

[rauanmayemir]

I think this is related to #337.

From what I've gathered looking into the code structure and issues, the main obstacle to moving forward with adopting buf is that large clients like kubectl directly depend on this repository and protobuf structure.

I found gnostic's protoc-gen-openapi more natural for gRPC-first stack than the grpc-gateway's plugin.
Gently pinging @timburks to ask about the next steps or priorities.

Maybe we need to wait for the unbundling of gnostic first before this plugin could be updated. But if IUUC, making protoc-gen-openapi use different protobuf schemas wouldn't break much because openapi annotation schemas are only needed for protoc-gen-openapi, not the gnostic itself (i.e the part that converts protobuf from openapi).

[hbjydev]

I think this is related to #337.

From what I've gathered looking into the code structure and issues, the main obstacle to moving forward with adopting buf is that large clients like kubectl directly depend on this repository and protobuf structure.

Hi there,

So it's not really related to #337, this isn't trying to make gnostic or protoc-gen-openapi use Buf for its dependencies or anything.

Basically, Buf has a concept of "remote plugins". They essentially let people who don't want to download the binaries for each protoc plugin use them directly through buf's Schema Registry. They are only there to make it possible to use protoc-gen-openapi work as a Buf plugin.

Hope that clarifies a little bit, but I'm happy to give it another go if not, haha.

[timburks]

@rauanmayemir That's right - we set up github.com/google/gnostic-models to provide some isolation. I think that has been around long enough now that we can start restructuring and other improvements to work well with Buf.

[conbon]

Any further thoughts or movement on this?

[timburks]

Reading up, it looks like this is about pointing buf to a locally-installed version of protoc-gen-openapi. Has someone already done this? If something needs to be uploaded to the gnostic org, I'll do that, but I'm not clear on what that is (yet).

[timburks]

... or do we need a PR on https://github.com/bufbuild/plugins ? (edit: or an issue like this one bufbuild/plugins#380)

[mfridman]

Hey @timburks 👋 , I can probably help with that (I help maintain bufbuild/plugins).

This particular plugin has come up a lot recently, and if you'd like, we can publish it as a Remote Plugin to https://buf.build/plugins which would satisfy the request above.

This enables folks to reference the plugin without having to download it locally. Let me know and I can follow up on this.

[mfridman]

There's a few new commits, but the latest tag is v0.6.9. What do you think of bumping the tag?