{"id":19839225,"url":"https://github.com/sudorandom/protoc-gen-connect-openapi","last_synced_at":"2026-02-12T23:10:09.059Z","repository":{"id":221678603,"uuid":"730677307","full_name":"sudorandom/protoc-gen-connect-openapi","owner":"sudorandom","description":"Plugin for generating OpenAPIv3 from protobufs matching the Connect RPC interface","archived":false,"fork":false,"pushed_at":"2026-02-01T12:24:06.000Z","size":3334,"stargazers_count":251,"open_issues_count":9,"forks_count":36,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-02-01T22:29:48.838Z","etag":null,"topics":["connectrpc","golang","grpc","protoc","protoc-plugin"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sudorandom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-12-12T12:45:54.000Z","updated_at":"2026-02-01T17:07:22.000Z","dependencies_parsed_at":"2024-02-24T15:25:47.009Z","dependency_job_id":"5fdff60f-d597-4e09-a111-f712ef70d718","html_url":"https://github.com/sudorandom/protoc-gen-connect-openapi","commit_stats":{"total_commits":121,"total_committers":8,"mean_commits":15.125,"dds":0.09090909090909094,"last_synced_commit":"f47765f25f42645f33c03c469ddc73336f5b171b"},"previous_names":["sudorandom/protoc-gen-connect-openapi"],"tags_count":90,"template":false,"template_full_name":null,"purl":"pkg:github/sudorandom/protoc-gen-connect-openapi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sudorandom%2Fprotoc-gen-connect-openapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sudorandom%2Fprotoc-gen-connect-openapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sudorandom%2Fprotoc-gen-connect-openapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sudorandom%2Fprotoc-gen-connect-openapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sudorandom","download_url":"https://codeload.github.com/sudorandom/protoc-gen-connect-openapi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sudorandom%2Fprotoc-gen-connect-openapi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29385586,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T22:07:52.078Z","status":"ssl_error","status_checked_at":"2026-02-12T22:07:49.026Z","response_time":55,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["connectrpc","golang","grpc","protoc","protoc-plugin"],"created_at":"2024-11-12T12:21:10.198Z","updated_at":"2026-02-12T23:10:09.040Z","avatar_url":"https://github.com/sudorandom.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# protoc-gen-connect-openapi\n[![Go](https://github.com/sudorandom/protoc-gen-connect-openapi/actions/workflows/go.yml/badge.svg)](https://github.com/sudorandom/protoc-gen-connect-openapi/actions/workflows/go.yml) [![Go Report Card](https://goreportcard.com/badge/github.com/sudorandom/protoc-gen-connect-openapi)](https://goreportcard.com/report/github.com/sudorandom/protoc-gen-connect-openapi) [![Go Reference](https://pkg.go.dev/badge/github.com/sudorandom/protoc-gen-connect-openapi.svg)](https://pkg.go.dev/github.com/sudorandom/protoc-gen-connect-openapi)\n\nGenerate OpenAPI v3.1 from protobuf matching the [Connect protocol](https://connectrpc.com/docs/protocol). With these [OpenAPI](https://www.openapis.org/what-is-openapi) specs, you can:\n\n- Generate Documentation (Elements, redoc, etc.)\n- Generate HTTP Clients for places where you cannot use gRPC (openapi-generator)\n- Datasource for automated endpoint validation/security testing\n- Datasource for monitoring dashboards\n- Many other things\n\nFeatures:\n- Support for OpenAPIv3.1 (which has support for jsonschema)\n- Support for [Twirp](https://twitchtv.github.io/twirp/docs/intro.html) ([more info](twirp.md))\n- Support for many [Protovalidate](https://github.com/bufbuild/protovalidate) options ([more info](protovalidate.md))\n- Support for many [OpenAPIv3](https://github.com/google/gnostic/blob/main/openapiv3/annotations.proto) options from the [google/gnostic project](https://github.com/google/gnostic) protobufs ([more info](gnostic.md))\n- Support for [gRPC-Gateway annotations](https://github.com/grpc-ecosystem/grpc-gateway) ([more info](grpcgateway.md))\n- Has [an easy interface](https://pkg.go.dev/github.com/sudorandom/protoc-gen-connect-openapi/converter) for generating OpenAPI specs in-process for Go\n\nExample Pipeline:\n- Protobuf file: [example](examples/basic.proto)\n- OpenAPI file: [example](examples/basic.openapi.yaml)\n- Generate documentation: [redocly example](examples/basic.png)\n\n```mermaid\nflowchart LR\n\nprotobuf(Protobuf) --\u003e|protoc-gen-connect-openapi| openapi(OpenAPI)\nopenapi --\u003e|elements| elements(API Documentation)\nopenapi --\u003e|openapi-generator| other-languages(Other Language Support)\nopenapi --\u003e|???| ???(Other Tooling!)\nclick elements \"https://github.com/stoplightio/elements\" _blank\nclick openapi-generator \"https://github.com/OpenAPITools/openapi-generator\" _blank\n```\n\n## Why?\n[Connect](https://connectrpc.com/docs/introduction) makes your gRPC service look and feel like a normal HTTP/JSON API, at least for non-streaming RPC calls. It does this without an extra network hop and an extra proxy layer because the same Connect server can speak [the Connect, gRPC and gRPC-Web protocols in a single port](https://connectrpc.com/docs/multi-protocol).\n\nThis is what a GET request looks like. Note that GET requests are available for methods with an option of `idempotency_level=NO_SIDE_EFFECTS`.\n```\n\u003e GET /connectrpc.greet.v1.GreetService/Greet?encoding=json\u0026message=%7B%22name%22%3A%22Buf%22%7D HTTP/1.1\n\u003e Host: demo.connectrpc.com\n\n\u003c HTTP/1.1 200 OK\n\u003c Content-Type: application/json\n\u003c\n\u003c {\"greeting\": \"Hello, Buf!\"}\n```\nWe can document this 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 and Connect and fully document it without the API consumers ever knowing what protobuf is or how to read it.\n\n## Install\n\n### Binaries\nYou can download pre-built binaries from the [Github releases page](https://github.com/sudorandom/protoc-gen-connect-openapi/releases/latest).\n\n### asdf\n\n```shell\n$ asdf plugin add protoc-gen-connect-openapi https://github.com/sudorandom/asdf-protoc-gen-connect-openapi.git\n$ asdf list all protoc-gen-connect-openapi\n$ asdf install protoc-gen-connect-openapi latest\n$ asdf global protoc-gen-connect-openapi latest\n```\n\n### Using Go\n\nIt isn't recommended, but you can also install directly using Go:\n```shell\ngo install github.com/sudorandom/protoc-gen-connect-openapi@latest\nprotoc-gen-connect-openapi --version\n```\n\nOr you can actually use `go run` directly from `buf.gen.yaml`, if that's the protobuf generation tool that you're using:\n\n```yaml\nversion: v2\nplugins:\n  - local: [\"go\", \"run\", \"github.com/sudorandom/protoc-gen-connect-openapi@latest\"]\n    out: gen\n```\n\n### Using \"go tool\" support\n\nIf you are already using Go, it may make sense to also use the new \"go tool\" support added in Go 1.24:\n```\ngo get -tool github.com/sudorandom/protoc-gen-connect-openapi@latest\ngo tool protoc-gen-connect-openapi --version\n```\n\nAgain, you can run the plugin in this mode with `buf generate` using this `buf.gen.yaml` file:\n\n```yaml\nversion: v2\nplugins:\n  - local: [\"go\", \"tool\", \"protoc-gen-connect-openapi\"]\n    out: gen\n```\n\n## Usage\n\n### Using buf\nThis plugin is now available [as a remote plugin in the BSR](https://buf.build/community/sudorandom-connect-openapi).\n\n```yaml\nversion: v2\nplugins:\n  - remote: buf.build/community/sudorandom-connect-openapi:v0.19.1\n    out: gen\n    opt:\n    - base=example.base.yaml\n```\n\nIf you use this config you don't actually need to do the install steps above. See the buf page on [remote plugins](https://buf.build/docs/bsr/remote-plugins/usage/) for more information on this.\n\nOf course, you can also use it locally, with a `buf.gen.yaml` that looks like this:\n```yaml\nversion: v2\nplugins:\n  - local: protoc-gen-connect-openapi\n    out: gen\n    opt:\n    - base=example.base.yaml\n```\nAnd then run `buf generate`. See [the documentation on buf generate](https://buf.build/docs/reference/cli/buf/generate#usage) for more help.\n\n### With protoc\nThis tool works as a plugin for protoc. Here's a basic example:\n```shell\nprotoc internal/converter/fixtures/helloworld.proto --connect-openapi_out=gen\n```\n\nWith the JSON format:\n```shell\nprotoc internal/converter/fixtures/helloworld.proto \\\n    --connect-openapi_out=gen \\\n--connect-openapi_opt=format=json\n```\n\nWith a base OpenAPI file and without all of the streaming content type:\n```shell\nprotoc internal/converter/fixtures/helloworld.proto \\\n    --connect-openapi_out=gen \\\n    --connect-openapi_opt=base=example.base.yaml,content-types=json\n```\n\nSee `protoc --help` for more protoc options.\n\n### Protovalidate Support\nprotoc-gen-connect-openapi also has support for many [Protovalidate](https://github.com/bufbuild/protovalidate) annotations. Note that not every Protovalidate constraint translates clearly to OpenAPI.\n\n[See the Protovalidate documentation page for more information](protovalidate.md)\n\n### gRPC-Gateway annotations\nprotoc-gen-connect-openapi also has support for the [gRPC-Gateway annotations](https://grpc-ecosystem.github.io/grpc-gateway/docs/tutorials/adding_annotations/) provided by the [google/api/annotations.proto](https://github.com/googleapis/googleapis/blob/master/google/api/annotations.proto).\n\n[See the gRPC-Gateway annotation documentation page for more information](grpcgateway.md)\n\n### Gnostic Support\nprotoc-gen-connect-openapi also has support for the [OpenAPI v3 annotations](https://github.com/google/gnostic/blob/main/openapiv3/annotations.proto) provided by the [google/gnostic project](https://github.com/google/gnostic).\n\n[See the gnostic documentation page for more information](gnostic.md)\n\n## Options\n| Option                    | Values | Description                                                                                                                                                   |\n|----------------------------|---|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| allow-get                  | - | For methods that have `IdempotencyLevel=IDEMPOTENT`, this option will generate HTTP `GET` requests instead of `POST`.                                              |\n| base                       | `{filepath}` | The path to a base OpenAPI file to populate fields that this tool doesn't populate. This option does not work when used with the remote plugin.         |\n| content-types              | `json;proto` | Semicolon-separated content types to generate requests/responses                                                                                        |\n| disable-default-response    | - | Disables the generation of the default `200 OK` response for all operations. Only explicit responses (e.g., from `google.api.http` annotations) will be included. |\n| format                     | `yaml` or `json` | Which format to use for the OpenAPI file, defaults to `yaml`.                                                                                       |\n| fully-qualified-message-names | - | Use fully qualified message names as the \"title\" for OpenAPI schemas. So it will be displayed as `company.users.administration.v1.User` instead of `User`.      |\n| ignore-googleapi-http      | - | [DEPRECATED] Use plugins=connectrpc;gnostic;protovalidate;twirp instead. Ignore google.api.http options on methods when generating openapi specs                                                                                          |\n| only-googleapi-http        | - | [DEPRECATED] Use plugins=google.api.http;gnostic;protovalidate instead. Only generate routes for methods that have explicit `google.api.http` annotations. Methods without annotations will be skipped.                                   |\n| include-number-enum-values | - | Include number enum values beside the string versions, defaults to only showing strings                                                                            |\n| override                   | `{filepath}` | The path to an override OpenAPI file to override schema components generated by the plugin. This option does not work when used with the remote plugin. |\n| path                       | `{filepath}` | Output filepath, defaults to per-proto file output if not given.  When using [buf](https://github.com/bufbuild/buf), generating multiple files to the same path requires additional configuration to avoid overwriting files. See [#159](https://github.com/sudorandom/protoc-gen-connect-openapi/issues/159).                                                                            |\n| path-prefix                | `{path}` | Prefixes the given string to the beginning of each HTTP path.                                                                                               |\n| features                   | `{feature1};{feature2};[...]` | Semicolon-separated list of features to enable. Options: `connectrpc`, `google.api.http`, `twirp`, `gnostic`, `protovalidate`; Default: `connectrpc;google.api.http;gnostic;protovalidate`. If this option is used, only the specified features will be enabled. |\n| allowed-visibilities   | `{visibility1};{visibility2};[...]` | Semicolon-separated list of visibility labels to include. If an element (service, method, message, enum, enum value, or field) has a `google.api.visibility` rule, it will only be included in the generated OpenAPI specification if its visibility label is in this list. If this option is omitted, elements with visibility rules are filtered out by default. Elements without visibility rules are always included. |\n| proto                      | - | Generate requests/responses with the protobuf content type                                                                                                         |\n| services                   | `{service_name}` | Specifies which services to include in the generated OpenAPI specification. If omitted, all services are included. The service name must be fully qualified (e.g., \"package.name.ServiceName\"). Wildcards (`*` and `**`) are supported; `*` matches a single package segment, while `**` matches multiple. This option can be provided multiple times to include multiple services.  |\n| short-operation-ids        | - | Set the operationId to shortServiceName + \"_\" + method short name instead of the full method name.                                                                 |\n| short-service-tags         | - | Use the short service name instead of the full name for OpenAPI tags.                                                                                              |\n| trim-unused-types          | - | Remove types that aren't references from any method request or response.                                                                                           |\n| with-google-error-detail   | - | Enables the generation of error details using error_details.proto from google.rpc                                                                                  |\n| with-proto-annotations     | - | Add protobuf type annotations to the end of descriptions so users know the protobuf type that the field converts to.                                               |\n| with-proto-names           | - | Use protobuf field names instead of the camelCase JSON names for property names.                                                                                   |\n| with-streaming             | - | Generate OpenAPI for client/server/bidirectional streaming RPCs (can be messy).                                                                                    |\n| without-default-tags       | - | Avoid appending default tags in the resulting OAS doc. All tags need to be explicitly defined through annotations.                                                 |\n\n### Features\n\nThe `features` option allows you to control which protocol-specific annotations and functionalities are enabled during OpenAPI generation. This is useful for tailoring the output to your specific needs and avoiding unnecessary processing.\n\nAt least one of the following features is required: `connectrpc`, `google.api.http`, or `twirp`. These features dictate how RPC methods are translated into HTTP endpoints in the OpenAPI specification.\n\nAvailable features:\n- `connectrpc`: Enables support for Connect RPC.\n- `google.api.http`: Enables support for `google.api.http` annotations (gRPC-Gateway style).\n- `twirp`: Enables support for Twirp RPC.\n- `gnostic`: Enables support for Gnostic OpenAPI v3 annotations.\n- `protovalidate`: Enables support for Protovalidate annotations.\n\nExamples:\n\n- **Enable only ConnectRPC support:**\n  ```yaml\n  opt:\n    - features=connectrpc\n  ```\n\n- **Enable Google API HTTP and Protovalidate support:**\n  ```yaml\n  opt:\n    - features=google.api.http;protovalidate\n  ```\n\n- **Enable all features:**\n  ```yaml\n  opt:\n    - features=connectrpc;google.api.http;twirp;gnostic;protovalidate\n  ```\n\n### Contributing\nContributions are accepted and welcome! Please make sure that all tests pass locally for you. You normally can use normal Go tooling to run tests but if you change any protobuf files in `internal/converter/testdata/`, you need to run this command to ensure the related DescriptorSet gets updated:\n```shell\ngo generate ./internal/converter/testdata\n```\nThis exists because it's the easiest way to pull in buf dependencies in a reliable way.\n\nOtherwise, tests are run with:\n```shell\ngo test ./...\n\n# or, if you prefer:\njust test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsudorandom%2Fprotoc-gen-connect-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsudorandom%2Fprotoc-gen-connect-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsudorandom%2Fprotoc-gen-connect-openapi/lists"}