Skip to content

Update readme to fix #286 #287

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sudorandom merged 1 commit into from
Sep 24, 2026
Merged

Update readme to fix #286 #287

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,23 +179,22 @@ protoc-gen-connect-openapi also has support for the [OpenAPI v3 annotations](htt
## Options
| Option | Values | Description |
|----------------------------|---|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| allow-get | - | For methods that have `IdempotencyLevel=IDEMPOTENT`, this option will generate HTTP `GET` requests instead of `POST`. |
| allow-get | - | For methods that have `IdempotencyLevel=NO_SIDE_EFFECTS`, this option will generate HTTP `GET` requests instead of `POST`. |
| asyncapi-path | `{filepath}` | Output filepath for the generated AsyncAPI v3.1 specification. If provided, the generator will write an AsyncAPI document documenting any client, server, or bidirectional streaming endpoints as WebSocket channels (conforming to the routing of [grpc-websocket-proxy](https://github.com/tmc/grpc-websocket-proxy)). |
| asyncapi-channel-template | `{template}` | Template pattern to customize the channel path mapping for WebSocket endpoints in the AsyncAPI spec. Available placeholders: `{package}`, `{service}`, `{method}`. Defaults to `/ws/{package}.{service}/{method}`. |
| 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. |
| content-types | `json;proto` | Semicolon-separated content types to generate requests/responses |
| 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. |
| format | `yaml`, `json`, or `jsonschema` | Which format to use for the output file, defaults to `yaml`. `yaml` and `json` render an OpenAPI document. `jsonschema` renders a standalone JSON Schema (draft 2020-12) document containing only the message and enum schemas, with every type under `$defs`; see [JSON Schema output](#json-schema-output). |
| 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`. |
| ignore-googleapi-http | - | [DEPRECATED] Use plugins=connectrpc;gnostic;protovalidate;twirp instead. Ignore google.api.http options on methods when generating openapi specs |
| 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. |
| ignore-googleapi-http | - | [DEPRECATED] Use features=connectrpc;gnostic;protovalidate;twirp instead. Ignore google.api.http options on methods when generating openapi specs |
| only-googleapi-http | - | [DEPRECATED] Use features=google.api.http;gnostic;protovalidate instead. Only generate routes for methods that have explicit `google.api.http` annotations. Methods without annotations will be skipped. |
| include-number-enum-values | - | Include number enum values beside the string versions, defaults to only showing strings |
| 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. |
| 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). |
| path-prefix | `{path}` | Prefixes the given string to the beginning of each HTTP path. |
| 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. |
| 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. |
| proto | - | Generate requests/responses with the protobuf content type |
| 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. |
| short-operation-ids | - | Set the operationId to shortServiceName + "_" + method short name instead of the full method name. |
| short-service-tags | - | Use the short service name instead of the full name for OpenAPI tags. |
Expand All @@ -204,6 +203,7 @@ protoc-gen-connect-openapi also has support for the [OpenAPI v3 annotations](htt
| with-google-error-detail | - | Enables the generation of error details using error_details.proto from google.rpc |
| with-proto-annotations | - | Add protobuf type annotations to the end of descriptions so users know the protobuf type that the field converts to. |
| with-proto-names | - | Use protobuf field names instead of the camelCase JSON names for property names. |
| with-service-descriptions | - | Appends service names and their comments to the end of `info.description`. |
| with-streaming | - | Generate OpenAPI for client/server/bidirectional streaming RPCs (can be messy). |
| without-default-tags | - | Avoid appending default tags in the resulting OAS doc. All tags need to be explicitly defined through annotations. |
| without-field-behavior-prefixes | - | Omit description prefixes from `google.api.field_behavior` annotations (`OPTIONAL`, `IMMUTABLE`, `UNORDERED_LIST`, `NON_EMPTY_DEFAULT`, `IDENTIFIER`). OpenAPI `required`, `readOnly`, and `writeOnly` are still applied. |
Expand Down
Loading