Today, ConnectRPC isn’t just a library. It is the core of a toolchain that makes traditional protoc workflows look completely dated. Companies like Anthropic are using it in production to power their SDKs, even maintaining their own ConnectRPC library in Rust.

Let’s look at how far things have come and how tools like Buf Remote Plugins, Protobuf SDKs, FauxRPC, and native HTTP/3 are changing API development.

Code Generation

One of my biggest complaints in Working with Protobuf in 2024 was the compatibility matrix from hell. Managing local installations of protoc, protoc-gen-go, and half a dozen other plugins was a miserable onboarding experience. If one person had a slightly different version of a plugin, the generated code drifted, and the CI build would fail for reasons that took twenty minutes to track down.

We can finally stop doing that. Buf Remote Plugins effectively killed the “it works on my machine” version of protoc. By pointing buf.gen.yaml to remote plugins on the Buf Schema Registry (BSR), we get deterministic, zero-install code generation.

# buf.gen.yaml in 2026
version: v2
plugins:
  - remote: buf.build/connectrpc/go:v1.19.1
    out: gen/go
    opt: paths=source_relative
  - remote: buf.build/protocolbuffers/go:v1.34.1
    out: gen/go
    opt: paths=source_relative

Your CI pipeline doesn’t need a bloated custom Docker image packed with binaries anymore. You just need the buf CLI. New hires clone the repo, run one command, and they’re done. It’s the level of “it just works” that we should have had a decade ago.

First-Class IDE Support

Writing Protobuf used to feel like coding in a glorified Notepad. We lacked the basic editor intelligence that almost every other major language enjoys.

That changed in early 2026 when Buf released a production-grade Language Server Protocol (LSP) server for Protobuf. It’s bundled directly into the buf CLI, which means whether you use VSCode or Neovim, you finally get go-to-definition and reference finding that actually works.

The LSP is workspace-aware, too. You can cmd-click an imported message from a third-party library and jump straight to the definition on the BSR without manually syncing files. It also catches syntax errors and duplicate modifiers before you even try to compile, which saves you from that annoying “context switch to terminal, run build, see error, switch back” loop.

Format, Lint, and Breaking Changes

The Buf CLI also provides the kind of guardrails that keep a team from moving into “legacy debt” territory too quickly.

If you’ve ever sat through a PR review where someone spent ten comments arguing about whether a field should be camelCase or snake_case, buf fmt and buf lint are for you. They end the debate. You run the command, the code is formatted, and the team moves on to actually solving problems.

The real winner is buf breaking. In a microservices setup, accidentally deleting a field or changing a data type in your schema is a great way to wake up the on-call engineer. By running buf breaking in CI, you verify the current schema against previous commits. It catches destructive changes before they hit the main branch, ensuring your contracts stay stable without requiring a human to manually audit every .proto change.

Data Validation

Validation has historically been a tedious chore. Writing endless if req.Age < 0 or if req.Email == "" checks in every single handler is a waste of time and a magnet for bugs.

protovalidate (which recently hit v1.0) moves those rules directly into the Protobuf schema. Since it’s built on Google’s Common Expression Language (CEL), you can do more than just check for nulls; you can write complex cross-field logic, like ensuring a “start date” is always before an “end date.”

By dropping the protovalidate interceptor into your server, requests are automatically validated before they touch your business logic. But the real “aha!” moment is the frontend. Your TypeScript client can run these same rules in the browser before the request even leaves. No more maintaining a separate Zod or Yup schema that inevitably gets out of sync with the backend. One source of truth, enforced everywhere.

Docs and Mocks

Sharing a gRPC endpoint used to be a pain; you couldn’t just hand someone a cURL command and expect it to work. ConnectRPC solved that fundamental issue by supporting standard HTTP/1.1 and JSON. But to truly treat these services like REST APIs, we needed the documentation tooling to match. That is why I spent part of 2024 working on protoc-gen-connect-openapi.

Now, Self-Documenting Connect Services are essentially the default for me. Because ConnectRPC skips binary framing for unary calls and uses standard HTTP status codes, we can generate an OpenAPI spec directly from the Protobuf definitions. You can spin up a Swagger UI directly from your server, let external users test with JSON, and keep your strict internal contracts intact.

We’ve also mostly solved the “waiting for the backend” bottleneck. FauxRPC uses your Protobuf descriptors to spin up a mock server in seconds. When you pair it with protovalidate, the fake data is actually realistic enough to build a frontend against. Some teams are even running FauxRPC in Testcontainers for integration tests, which is much cleaner than trying to manage a “staging” backend for every test run.

Why gRPC-Web Failed

To understand why ConnectRPC won the frontend, you have to look at the history of the protocol. Native gRPC relies on HTTP/2 trailers for status codes, but browsers do not expose those trailers to JavaScript. This originally made gRPC effectively unusable on the web.

The official solution to this problem was gRPC-Web. Its intended goal was straightforward: allow developers to use gRPC directly from web applications. As far as that specific goal goes, it was a success. You could finally make gRPC calls from a browser.

But there is a big difference between a technical success and a widely adopted standard. gRPC-Web never truly took off for a number of reasons. First, it was fundamentally unfriendly to modern infrastructure. It required a separate proxy (usually Envoy) just to translate the frontend requests into something the gRPC backend could understand. This added immediate operational overhead to every project.

Worse, it preserved the most frustrating parts of gRPC. Every single request returned a 200 OK, regardless of whether the server crashed or the resource was missing. It was a baffling design choice that broke the internet’s existing contract for observability. You could not rely on standard load balancer metrics, standard browser dev tools, or your generic APM to see if your site was actually healthy. You were forced to use specialized, protocol-aware tooling just to perform basic debugging. If I have to open a dedicated “gRPC-aware” network tab just to see why a login failed, I feel like it hasn’t actually earned the “web” part of gRPC-Web name.

ConnectRPC stepped in and completely erased the proxy requirement. It also fixed the integration issues with the traditional web. A unary JSON request in ConnectRPC acts exactly like a standard REST call. If a resource is missing, you get a real 404 Not Found, and your existing monitoring stack just works. It gave frontend developers the familiar, straightforward debugging experience they actually wanted while keeping the strict schema safety that backend teams need.

Why it’s my default choice

In 2024, ConnectRPC was about making gRPC more approachable. Now, the underlying protocol is almost an implementation detail. We get the benefits of typed schemas and code generation, but the friction of the “gRPC tax” is gone.

If you’re still hand-rolling JSON/REST APIs or wrestling with legacy gRPC-go stubs and Envoy proxies, it’s time to move on. The tools are ready, the workflow is better, and your on-call engineer will thank you.

In today’s interconnected world, APIs (Application Programming Interfaces) are the glue that connects computers. They allow different applications to talk to each other, share data, and perform actions. However, traditional methods of creating APIs often lead to frustrating challenges: breaking changes in JSON APIs, silent failures due to missing fields, frontend and backend drift, or schema mismatches that result in the classic “works on my machine” excuse.

Imagine a real-world scenario where the backend team renames a userId field to user_id and deploys their changes. Instantly, the frontend checkout process breaks in production because the API had no strict enforcement to catch the mismatch.

This is where contract-based APIs come in. A contract-based API is one where the schema is defined first in a formal specification, and both client and server are generated or validated against that contract. They reduce ambiguity and enforce consistency across services.

The Power of Pre-defined API Contracts

A contract-based API defines exactly what data can be exchanged, in what format, and what actions can be performed. This strict, pre-defined agreement unlocks several immediate advantages:

• Improved Developer Experience: Developers on both sides (client and server) have a clear understanding of what is expected, making integration smoother.
• Automated Documentation: Contracts serve as self-documenting artifacts. This reduces the need for manual documentation maintenance and ensures the docs stay in sync with the actual API implementation.
• Reduced Errors: Mismatched data formats or API changes become less likely, leading to fewer bugs. Contracts act as a validation layer that catches potential issues early.
• Easier Integration: Contracts act as a single source of truth. Developers can quickly understand how to interact with the API without extensive back and forth communication.
• Streamlined Development: These APIs often enable tools to automatically generate code for both client and server implementations. This eliminates manual boilerplate so you can focus on core logic.

Protobuf: The Language of APIs

In modern distributed systems, the foundation of many contract-based APIs lies in Protocol Buffers (protobuf). It is a language-neutral data format specifically designed for structured messages.

Unlike JSON, which is a text-based format designed to be human-readable, Protobuf is a binary format. This means you trade the ability to natively read the raw data in transit for significant performance gains:

• Smaller Message Sizes: Protobuf messages are compact and efficient, which leads to faster transmission and reduced bandwidth usage.
• Faster Parsing: Parsing binary protobuf messages is significantly faster compared to traditional formats like JSON or XML.
• Built-in Versioning: Protobuf uses field numbers (the = 1, = 2 in the code below) to identify data. This allows for excellent backward and forward compatibility. You can add new fields without breaking older clients that do not know about them yet.
• Cross-language Compatibility: Protobuf definitions are language-agnostic. Code for interacting with the API can be generated for almost any modern programming language.

Because the data is binary, you cannot simply open your browser’s network tab and read the payloads by default. You will usually need to rely on modern browser extensions (like the gRPC-Web or Connect dev tools) to decode the traffic. It also requires setting up specialized tooling and build steps to compile the generated code.

Here is a basic example of a .proto file defining messages for a user and an address:

syntax = "proto3";

message User {
  string name = 1;
  int32 id = 2;
  string email = 3;
  Address address = 4;
}

message Address {
  string street = 1;
  string city = 2;
  string state = 3;
  string zip = 4;
}

In this example, the User message has fields for name, ID, email, and an Address message. These defined structures ensure consistent data exchange between applications.

Key idea: Protobuf relies on immutable field numbers instead of field names. This golden rule guarantees backward and forward compatibility.

gRPC: Building APIs on a Solid Foundation

gRPC (gRPC Remote Procedure Call) is a high-performance framework that builds upon protobuf’s strengths. It provides a powerful way to implement remote procedure calls, allowing applications to interact using clients generated for each language.

Introducing Services and Request/Response Types with gRPC

We can expand the .proto file to define a service called UserService with methods for user management:

syntax = "proto3";

service UserService {
  rpc CreateUser(CreateUserRequest) returns (User) {}
  rpc GetUser(GetUserRequest) returns (User) {}
}

message CreateUserRequest {
  User user = 1;
}

message GetUserRequest {
  int32 id = 1;
}

This example defines a UserService with two methods: CreateUser and GetUser. Each method takes a specific request message and returns a response.

Notice how clear the intention is. A helpful mental model to contrast modern APIs is:

• REST is resource-oriented (relying on URLs and HTTP verbs).
• gRPC is action-oriented (relying on explicit methods).

A reader of this spec does not have to map vague HTTP verbs like “POST” to actions like “create.” Also, these method names are greppable. It is trivial to locate every use of CreateUser across several repositories, making refactoring and impact analysis much easier.

Server Reflection

Another powerful feature of the gRPC ecosystem is Server Reflection. This allows clients or debugging tools (like Postman or grpcurl) to query the server at runtime to discover the available services and methods. This eliminates the need to distribute .proto files to developers just so they can explore the API structure.

Distributing API Contracts

Defining a contract is only half the battle. How do the frontend and backend teams actually share that .proto file? If the schema is not easily accessible, the contract is useless.

In practice, teams usually solve this distribution problem in one of three ways:

1. Monorepos: Storing the backend, frontend, and API definitions in a single repository so all code shares the same source of truth.
2. Package Managers: Generating the client SDKs in a CI/CD pipeline and publishing them as internal NPM, Maven, or Go packages.
3. Schema Registries: Using dedicated tools like the Buf Schema Registry to manage, version, and distribute Protobuf files securely across an organization.

What about public APIs?

Historically, strict RPC contracts were tough for external, public-facing APIs. If your primary consumers were third-party developers, handing them a raw Protobuf file or expecting them to set up gRPC clients caused massive friction. They just wanted to use standard REST with JSON.

This is where tools like ConnectRPC shine. ConnectRPC allows you to define your API using Protobuf, but it automatically exposes endpoints that support standard HTTP/1.1 and JSON serialization as a fallback format.

This hybrid approach also solves the local debugging problem. You can configure ConnectRPC to use JSON during local development specifically so you can read the network tab in plain text, and then flip it to highly efficient binary for production. In practice, you write Protobuf once, and get both gRPC and REST/JSON APIs for free.

Even better, because the source of truth is still Protobuf, you can use ecosystem plugins to automatically generate an OpenAPI specification directly from your .proto files. You get a highly maintainable, contract-driven architecture on the backend, while your external users can still curl standard REST endpoints, read plain JSON, and explore your API via a generated Swagger UI. It offers the best of both worlds without compromising the developer experience on either side.

Key idea: Tools like ConnectRPC allow you to maintain strict internal Protobuf contracts while exposing standard REST/JSON APIs to external consumers.

Alternatives

While Protobuf and gRPC are a powerful duo, there are other contract-based API solutions to consider depending on your architecture:

• OpenAPI (Swagger): Contracts are not exclusive to RPC. You can use OpenAPI to define strict contracts for RESTful services. However, a harsh reality of the industry is that OpenAPI specs often drift from the actual code because they are bolted on after the fact. To make OpenAPI truly safe, teams must rely on strict framework integration (like FastAPI in Python or tsoa in Node) where the code generates the spec, or vice versa.
• GraphQL: Arguably the most mainstream contract-driven API paradigm for frontend developers. Its strictly typed schema defines the exact shape of the available data. Unlike gRPC, which has fixed responses, GraphQL allows the client to dictate the exact payload it wants to receive.
• Twirp: Developed by Twitch, Twirp is a lightweight RPC framework built on top of Protobuf and HTTP/1.1. It shares similarities with ConnectRPC but focuses on absolute simplicity. It avoids the complexity of HTTP/2 and gRPC streams while still providing generated clients, making it an excellent alternative if full gRPC is overkill for your needs.
• Thrift: Originally developed at Facebook, Thrift is a language-neutral protocol for defining service contracts similar to Protobuf. It is often found in large-scale data environments and supports various RPC protocols.
• tRPC: This tool defines the API schema directly in TypeScript code to be reused on both the client and the server. While it often pairs with libraries like Zod for runtime validation, it lacks true language-agnostic safety across the network boundary since it relies entirely on a TypeScript ecosystem.
• Avro: This format uses JSON-like schemas but stores data in a compact binary format. It is a staple in the Apache Kafka ecosystem for streaming data pipelines. It handles schema evolution differently than Protobuf (often sending the schema alongside the data), making it highly flexible for dynamic systems.

When NOT to Use API Contracts

While these tools are powerful, they are not a silver bullet. You should reconsider using strict API contracts if:

• You are building small projects or MVPs: The initial setup, code generation, and boilerplate overhead might slow down your speed of delivery when rapid iteration is the top priority.
• Simplicity for external consumers outweighs strict contracts: If you are building a straightforward public API and are not using a hybrid tool like ConnectRPC, raw JSON over REST remains the path of least resistance for third-party developers.
• Your team lacks tooling maturity: Implementing gRPC or Protobuf requires solid CI/CD pipelines and a team that is comfortable managing build steps, code generation, and backward-compatible schema evolutions.

Key idea: Strict API contracts add overhead and may not be suitable for small MVPs, simple public APIs, or teams lacking tooling maturity.

Conclusion

Contract-based APIs offer a significant advantage in building robust and scalable communication between applications. Protobuf and gRPC provide a powerful combination for defining clear contracts and generating highly efficient code.

As a general rule of thumb: if you are building an early-stage prototype, stick to what is fast and familiar. But if you are scaling a complex system across multiple teams and services, contract-based APIs transition from a nice-to-have to an absolute necessity. Once multiple teams depend on your API, contracts stop being optional. They are how you avoid chaos.

For more on the plugin itself, refer to my older post that introduces protoc-gen-connect-openapi or the github repo which has some more updates.

This post is about a new way to use this functionality, from a Go library. This Go API provides a simpler interface to generate OpenAPI from protobuf descriptors. You see, protoc plugins accept a *pluginpb.CodeGeneratorRequest and return a *pluginpb.CodeGeneratorResponse. The request type, in particular, is hard to use from Go. You have to encode every option you want to use into a single string. This is fine for a CLI but it’s not very friendly for a Go library. But now that I made this library it is much easier to generate OpenAPI specs anywhere you run Go. Let’s look at some examples.

Generating OpenAPI

First, let’s see how we can use this plugin to generate OpenAPI YAML from your protobuf definitions:

openapiBody, _ := converter.GenerateSingle(
    converter.WithGlobal(),
    converter.WithBaseOpenAPI([]byte(`
openapi: 3.1.0
info:
  title: OpenAPI Documentation of gRPC Services
  description: This is documentation that was generated from [protoc-gen-connect-openapi](https://github.com/sudorandom/protoc-gen-connect-openapi).
  version: 0.1.2
`)))
fmt.Println(string(openapiBody))

With a few short lines, you now have OpenAPI YAML representation of your ConnectRPC services.

openapi: 3.1.0
info:
  title: OpenAPI Documentation of gRPC Services
  description: This is documentation that was generated from [protoc-gen-connect-openapi](https://github.com/sudorandom/protoc-gen-connect-openapi).
paths:
  /connectrpc.eliza.v1.ElizaService/Say:
    post:
      tags:
        - connectrpc.eliza.v1.ElizaService
      summary: Say
      operationId: connectrpc.eliza.v1.ElizaService.Say
      parameters:
        - name: Connect-Protocol-Version
          in: header
          required: true
          schema:
            $ref: '#/components/schemas/connect-protocol-version'
        - name: Connect-Timeout-Ms
          in: header
          schema:
            $ref: '#/components/schemas/connect-timeout-header'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/connectrpc.eliza.v1.SayRequest'
        required: true
      responses:
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/connect.error'
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/connectrpc.eliza.v1.SayResponse'
  /connectrpc.eliza.v1.ElizaService/Converse: {}
  /connectrpc.eliza.v1.ElizaService/Introduce: {}
components:
  schemas:
    connectrpc.eliza.v1.SayRequest:
      type: object
      properties:
        sentence:
          type: string
          title: sentence
      title: SayRequest
      additionalProperties: false
    connectrpc.eliza.v1.SayResponse:
      type: object
      properties:
        sentence:
          type: string
          title: sentence
      title: SayResponse
      additionalProperties: false
    connect-protocol-version:
      type: number
      title: Connect-Protocol-Version
      enum:
        - 1
      description: Define the version of the Connect protocol
      const: 1
    connect-timeout-header:
      type: number
      title: Connect-Timeout-Ms
      description: Define the timeout, in ms
    connect.error:
      type: object
      properties:
        code:
          type: string
          examples:
            - CodeNotFound
          enum:
            - CodeCanceled
            - CodeUnknown
            - CodeInvalidArgument
            - CodeDeadlineExceeded
            - CodeNotFound
            - CodeAlreadyExists
            - CodePermissionDenied
            - CodeResourceExhausted
            - CodeFailedPrecondition
            - CodeAborted
            - CodeOutOfRange
            - CodeInternal
            - CodeUnavailable
            - CodeDataLoss
            - CodeUnauthenticated
          description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
        message:
          type: string
          description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
        detail:
          $ref: '#/components/schemas/google.protobuf.Any'
      title: Connect Error
      additionalProperties: true
      description: 'Error type returned by Connect: https://connectrpc.com/docs/go/errors/#http-representation'
    google.protobuf.Any:
      type: object
      properties:
        type:
          type: string
        value:
          type: string
          format: binary
        debug:
          type: object
          additionalProperties: true
      additionalProperties: true
      description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.
security: []
tags:
  - name: connectrpc.eliza.v1.ElizaService

This file is truncated to only show a single endpoint and related types. To see the full file, click here. The converter.WithGlobal() option uses the global protobuf registry as the source. If you want to use specific (or protobuf file descriptors not in that registry), you can pass in any protoregistry.GlobalFiles value to the converter.WithFiles() option. With converter.WithBaseOpenAPI(), you can specify a base OpenAPI spec that will be used as the basis for the generated one. Here you can add a description, version, security schemes, link to other documentation, etc.

But what’s the practical use of this YAML?

Show the world what you can do

With a few additional lines of code, we can leverage one of the numerous OpenAPI documentation visualization tools to transform this YAML into a visually appealing and interactive web page. Here’s an example using Elements from Spotlight:

var tmplElements = template.Must(template.New("name").Parse(`<!doctype html>
<html lang="en">
	<head>
	<meta charset="utf-8">
	<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
	<title>OpenAPI Documentation</title>
	<script src="https://unpkg.com/@stoplight/elements@8.3.4/web-components.min.js"></script>
	<link rel="stylesheet" href="https://unpkg.com/@stoplight/elements@8.3.4/styles.min.css">
	</head>
	<body>

	<elements-api
		id="docs"
		router="hash"
		layout="sidebar"
	/>
	<script>
	(async () => {
		const docs = document.getElementById('docs');
		docs.apiDescriptionDocument = atob("{{ .DocumentBase64 }}");
	})();
	</script>

	</body>
</html>`))

func main() {
	mux := http.NewServeMux()
	mux.Handle(elizav1connect.NewElizaServiceHandler(&elizav1connect.UnimplementedElizaServiceHandler{}))
	openapiBody, err := converter.GenerateSingle(
		converter.WithGlobal(),
		converter.WithContentTypes(
			"json",
			"proto",
		),
		converter.WithStreaming(true),
        converter.WithAllowGET(true),
		converter.WithBaseOpenAPI([]byte(`
openapi: 3.1.0
info:
  title: OpenAPI Documentation of gRPC Services
  description: This is documentation that was generated from [protoc-gen-connect-openapi](https://github.com/sudorandom/protoc-gen-connect-openapi).
`)))
	if err != nil {
		log.Fatalf("err: %s", err)
	}
	generationTime := time.Now()

	mux.Handle("GET /openapi.html", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if err := tmplElements.Execute(w, struct{ DocumentBase64 string }{
			DocumentBase64: base64.StdEncoding.EncodeToString(openapiBody),
		}); err != nil {
			slog.Error("rendering_template", "error", err)
		}
	}))
	mux.Handle("GET /openapi.yaml", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		http.ServeContent(w, r, "openapi.yaml", generationTime, bytes.NewReader(openapiBody))
	}))

	addr := "127.0.0.1:6660"
	log.Printf("Starting connectrpc on http://%s", addr)
	log.Printf("OpenAPI Doc Page http://%s/openapi.html", addr)
	log.Printf("OpenAPI Spec http://%s/openapi.yaml", addr)
	srv := http.Server{
		Addr:    addr,
		Handler: mux,
	}
	if err := srv.ListenAndServe(); err != nil {
		log.Fatalf("error: %s", err)
	}
}

And here’s what it looks like whenever you hit http://127.0.0.1.:6660/openapi.html in a web browser:

To see the demo for yourself, click here!

In this example, we’re using the @stoplight/elements library to render the OpenAPI documentation. The tmplElements template embeds the generated OpenAPI YAML (Base64 encoded) into an HTML page, providing a user-friendly interface to explore your API’s endpoints, request/response structures, and more. Note that we’re using base64 so that none of the YAML characters accidentally escape the javascript string and mess everything up for us. You can also have the script load the OpenAPI spec from a URL, which is what many of the examples show.

You may also notice some additional options in this example, like converter.WithContentTypes(), converter.WithStreaming(true) and converter.WithAllowGET(true). These give you more control over content types, whether you want OpenAPI for streaming calls (which may be complicated to support for OpenAPI) and whether you want to generate documentation for GET requests, that Connect supports if you can set the idempotency_level option to NO_SIDE_EFFECTS. For more information on GET requests and a comprehensive list of available options, refer to the the Connect documentation and the protoc-gen-connect-openapi Go documentation, respectively.

Benefits of Self-Documenting Services

Clear and interactive documentation makes it easier for developers to understand and integrate with your APIs. This reduces the friction between teams and gives you something to point to in case there are questions about the API. Not everyone is fluent in reading protobuf, but HTTP documentation is much friendlier.

By generating documentation from protobufs, it is much easier for documentation to stay in sync with your codebase. Note that adding comments to your protobuf types, fields, services and methods also get carried over to this OpenAPI specification (and the generated protobuf/gRPC/gRPC-Web/Connect source code) so protobuf files can act as a single place to document everything about that service.

Conclusion

By combining the power of protoc-gen-connect-openapi with OpenAPI visualization tools, you can effortlessly generate self-documenting Connect services. This approach streamlines development, fosters collaboration, and empowers developers to consume your APIs effectively.

Here’s what an HTTP request looks like for a unary RPC with connect:

> POST /connectrpc.greet.v1.GreetService/Greet HTTP/1.1
> Host: demo.connectrpc.com
> Content-Type: application/json
>
> {"name": "Buf"}

< HTTP/1.1 200 OK
< Content-Type: application/json
<
< {"greeting": "Hello, Buf!"}

If you mark the endpoint as idempotency_level=NO_SIDE_EFFECTS then you can also call GET on the endpoint so the request body has to go into the query parameters. Here’s what that looks like:

> GET /connectrpc.greet.v1.GreetService/Greet?encoding=json&message=%7B%22name%22%3A%22Buf%22%7D HTTP/1.1
> Host: demo.connectrpc.com

< HTTP/1.1 200 OK
< Content-Type: application/json
<
< {"greeting": "Hello, Buf!"}

It’s that… simple? Elegant? No? If you’re not sold on ConnectRPC now then this may not be the post for you because the rest will talk about my new tool created for ConnectRPC; protoc-gen-connect-openapi.

Introducing protoc-gen-connect-openapi

protoc-gen-connect-openapi generates OpenAPI v3.1 files from protobuf files that match the API that the Connect protocol exposes.

We can document the Connect API as if it’s a real JSON/HTTP API… because it is, and the gRPC “flavor” isn’t so noticable due to Connect. With protoc-gen-connect-openapi you can declare your API using protobuf, serve it using gRPC/gRPC-WEb/Connect and fully document it without the API consumers ever knowing what protobuf is or how to read it. To me, this is the best of all worlds.

So, specifically, what good are OpenAPI files generated for Connect? What does that do? Well, first of all, it allows you to generate documentation with tools like redocly or elements.

Additionally, with tools like OpenAPI-Generator you can generate API clients for languages that Connect doesn’t support yet (for non-streaming methods).

flowchart LR

protobuf(Protobuf) -->|protoc-gen-connect-openapi| openapi(OpenAPI)
openapi -->|elements| docs(Gorgeous\nAPI Documentation)
openapi -->|redocly| docs
openapi -->|openapi-generator| other-languages(Languages that\nConnect doesn't\n support yet)
openapi -->|other tool| ???(Something equally amazing)
click elements "https://github.com/stoplightio/elements" _blank
click openapi-generator "https://github.com/OpenAPITools/openapi-generator" _blank
  

In summary, I hope this tool will extend the contract-based usage of protobuf along with ConnectRPC’s RPC-based API into further places with more documentation, more code generation, and additional validation.

For more information, check out the protoc-gen-connect-openapi repo on Github.