Generating OpenAPI documentation

[zdyxry]

I want to automatically generate openAPI documentation through proto like using grpc-gateway, how to do it in connect-go?

[akshayjshah]

Hm, that's a good question. Are you looking for documentation, like some HTML or text describing your API? Or are you looking for an OpenAPI specification that people can use to generate code and call your API?

(I'm just getting used to Github discussions. This seemed like a better fit for a discussion rather than an issue, so I moved it - hope you don't mind!)

[zdyxry]

Maybe the OpenAPI specification will suffice for my needs.

[akshayjshah]

I'm not sure how you'd produce an OpenAPI specification easily. You could deploy gRPC-Gateway in front of your connect-go server, then use protoc-gen-openapi to produce an OpenAPI specification for that...but that's certainly not something I'd want to do.

For what it's worth, you'd have the same problem with grpc-go.

[bokunodev]

hi, protoc-gen-openapi work. but who about http method and path?
that information is hidden untill we initialize the handler.

[bendiktv2]

In an ideal world, you could probably generate for all languages, and have a proper implementations, and a proper distribution of the .proto files (or something like the BSR) could serve as the documentation.

But openapi is pretty widespread and has support for many more things than just generating client/server. Some examples:
Postman can generate requests for all endpoints in the spec.
You can call the actual API to try out endpoints.

Also, we are still not living in an ideal world, and this would help tremendously of moving us there.

Serving connect-go behing a grpc-gateway is a no-go, as we are trying to remove the need for grpc-gateway at all 😂

[timostamm]

Well, you can generate gRPC for basically any language today, and connect-go will happily serve gRPC. The only major client left out is the browser, and we're working on that.

OpenAPI sure has it's benefits, but I think the user experience of going from protobuf to openapi to a client or other tool isn't really smooth. That said, an OpenAPI generator for the Connect protocol should be pretty straight-forward once you have a JSON schema for the request and response types.

[ansel1]

Is it possible to generate a grcp-gateway proxy in front of grpc server that would essentially wire-compatible with the connect-go protocol? I mean, do the grcp-gateway proto extensions provide enough flexibility to do that?

I'm thinking, since there is no native openapi generator for connect go, maybe I could decorate my proto files with google.api.http and protoc-gen-openapiv2/options/annotations.proto, and use protoc-gen-openapiv2 to generate swagger which accurately documents the connect-go protocol.

[bendiktv2]

Hello!
Now that you have implemented Connect for quite a few languages (including web), it might be a good time to revisit this discussion.

I would really appreciate it if there was a protobuf-plugin that would generate a static HTML page with documentation on how to use the API.

It could include links to Connect's GitHub to show how to start implementing a client for the API in whichever language they want (connect-es, connect-go, connect-kotlin etc).
It should also properly describe the REST JSON api, so that the client can choose to not yet buy into the Connect-ecosystem (in case of legacy systems with existing middlewares for applying known HTTP Headers/Authentication/Tracing). The models needs to use the correct casing (snake_case? camelCase? dependent on proto-field-name?) for every field, so no guesswork is needed.
There should also be a way to describe example responses.
There should also be a way to describe known error-responses, and error-details that might accompany it, and a mapping between the Connect status-code and HTTP status code.
There should also be a way to make a call to specify authentication-details and optional headers, and then call the API from the HTML, while allowing to modify the body. The response body and headers should be shown.
Optionally, the calling of the API would allow to use different codexes (JSON, gRPC, gRPC-web, Connect), where supported.

A lot of these things are present in Swagger/OpenAPI, but it is not a requirement for us that Connect's generated documentation uses that technology. By not choosing Swagger/OpenAPI, the emphasis becomes on documentation and exploration, rather than generation of client.

[MaxThom]

+1, would love see something like this! even an embded htmx?

[serverhorror]

OpenAPI and the ability to use option (google.api.http) = ... is a blocker for us.

We have a ton of existing clients and implementations, things we can not change because they are not even under our control.

It's as simple as this question:

• With connect, how would I make sure that the exposed path is honoring the options defined?

  We can't possibly rewrite all the clients and adding "custom" things in front of connect kind of defeats the purpose...

  syntax = "proto3";
  
  package greet.v1;
  
  import "google/api/annotations.proto";
  
  option go_package = "example/gen/pb/greet/v1;greetv1";
  message GreetRequest {
    string name = 1;
  }
  message GreetResponse {
    string greeting = 1;
  }
  service GreetService {
    rpc Greet(GreetRequest) returns (GreetResponse) {
  
      option (google.api.http) = {
        post: "/v1/greet"
        body: "name"
        response_body: "greeting"
      };
  
    };
  }
  

[timostamm]

@serverhorror, you can use vanguard-go to enable the google.api.http annotations. vanguard-go is similar to grpc-gateway, but it plugs into your server like any other middleware, and does not need code generation.

I do not believe that there is an OpenAPI generator for the Connect routes, but I'm quite sure there should be one for the the google.api.http annotations.

[Kryan90]

Just wanted to say I would love to see buf adopt this. Right now generating good openapi specs to use for existing documentation tools (redoc, rapidoc, etc). We have been using gnostic https://github.com/google/gnostic/tree/main/cmd/protoc-gen-openapi but its not something that seems to be actively maintained and is pretty specific to how google does things (like having to specify http annotations instead of using the default for gRPC paths)

It looks like there is some tooling starting to specifically target connect, but it would be great if buf directly supported some of this.
https://github.com/sudorandom/protoc-gen-connect-openapi

[prateeksriv]

+1 this

[tdorn]

Problem statement: I want to be able to use connect so that I don't have to continue to vend type-specific proto bindings to my customers. I want customers to be able to cURL/interact with a set of raw HTTP APIs. Right now, there's no way for people to discover the correct API paths and shapes without prior knowledge of my gRPC service paths, request/response protojson format, and intricate understanding of the connect protocol itself.

Please let me know if I'm wrong, but I think the above problem statement is the main reason why most folks will consider using connect. If there existed a well-supported way to generate static API docs for my service's connect-HTTP API spec, including streaming, then it would truly be a deal maker.

[perezd]

This is a great way to provide this for Connect: https://github.com/sudorandom/protoc-gen-connect-openapi

[tdorn]

I did see that. Unfortunately, it isn't maintained by you though ;( I don't want to put my entire company's API doc generation on someone's 78 star side proj. Have you considered adopting it?

[perezd]

We are actively exploring that! So at a minimum we would recommend it.

[veqryn]

Generating an OpenAPI spec for the json side of ConnectRPC would be a game changer.
You can load it into a swagger ui and let people explore your api in the browser.
You can load it into Postman.
There are so many tools that work with OpenAPI.