protoc-gen-connect-openapi

https://github.com/sudorandom/protoc-gen-connect-openapi
Admin
A `protoc` plugin that generates OpenAPI v3.1 specifications from Protocol Buffer definitions,...
Tokens:29,370
Snippets:433
Trust Score:9.3
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install the plugin

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/START_HERE.md

Install the latest version of the plugin using the Go toolchain.

```bash
go install github.com/sudorandom/protoc-gen-connect-openapi@latest
```

--------------------------------

### Install and run via Go

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/README.md

Direct installation using the Go toolchain and configuration for buf.gen.yaml.

```shell
go install github.com/sudorandom/protoc-gen-connect-openapi@latest
protoc-gen-connect-openapi --version
```

```yaml
version: v2
plugins:
  - local: ["go", "run", "github.com/sudorandom/protoc-gen-connect-openapi@latest"]
    out: gen
```

--------------------------------

### Building from source

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/plugin-entrypoint.md

Clone the repository and install the plugin using the Go toolchain.

```bash
git clone https://github.com/sudorandom/protoc-gen-connect-openapi.git
cd protoc-gen-connect-openapi
go install ./cmd/protoc-gen-connect-openapi
```

--------------------------------

### Install via asdf

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/README.md

Commands to add, list, and install the plugin using the asdf version manager.

```shell
$ asdf plugin add protoc-gen-connect-openapi https://github.com/sudorandom/asdf-protoc-gen-connect-openapi.git
$ asdf list all protoc-gen-connect-openapi
$ asdf install protoc-gen-connect-openapi latest
$ asdf global protoc-gen-connect-openapi latest
```

--------------------------------

### Define Service HTTP Mappings

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/googleapi-paths.md

Example of defining GET and POST methods within a service definition.

```proto
service Users {
  rpc GetUser(GetUserRequest) returns (User) {
    option (google.api.http) = {
      get: "/v1/users/{user_id}"
    };
  }
  
  rpc CreateUser(CreateUserRequest) returns (User) {
    option (google.api.http) = {
      post: "/v1/users"
      body: "*"
    };
  }
}
```

--------------------------------

### Installing via binary download

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/plugin-entrypoint.md

Download and set permissions for the pre-built binary from GitHub releases.

```bash
curl -L https://github.com/sudorandom/protoc-gen-connect-openapi/releases/latest -o /usr/local/bin/protoc-gen-connect-openapi
chmod +x /usr/local/bin/protoc-gen-connect-openapi
```

--------------------------------

### Install and run via Go tool support

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/README.md

Using Go 1.24+ tool support to manage and execute the plugin.

```shell
go get -tool github.com/sudorandom/protoc-gen-connect-openapi@latest
go tool protoc-gen-connect-openapi --version
```

```yaml
version: v2
plugins:
  - local: ["go", "tool", "protoc-gen-connect-openapi"]
    out: gen
```

--------------------------------

### Example of Gnostic Annotations in Protobuf

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/remote-plugin.md

This example demonstrates how to use gnostic annotations within a .proto file to define top-level OpenAPI document information, such as API title, version, and contact details. This approach is compatible with remote plugins.

```protobuf
syntax = "proto3";

package my.service.v1;

import "gnostic/openapi/v3/annotations.proto";

option (gnostic.openapi.v3.document) = {
  info: {
    title: "My Awesome API";
    version: "1.0.0";
    description: "This is a sample server for a pet store.";
    contact: {
      name: "API Support";
      url: "http://www.example.com/support";
      email: "support@example.com";
    }
    license: {
      name: "Apache 2.0";
      url: "http://www.apache.org/licenses/LICENSE-2.0.html";
    }
  }
};

service MyService {
  // ...
}
```

--------------------------------

### Configure OpenAPI Generation Options

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter.md

Examples demonstrating how to use various functional options to configure the converter's behavior.

```go
converter.Generate(
	converter.WithFiles(protoregistry.GlobalFiles),
)
```

```go
converter.Generate(
	converter.WithSourceFiles(commonTypesRegistry),
	converter.WithFiles(serviceRegistry),
)
```

```go
converter.Generate(converter.WithGlobal())
```

```go
converter.Generate(
	converter.WithGlobal(),
	converter.WithFormat("json"),
)
```

```go
baseContent := []byte(`
info:
  x-logo:
    url: https://example.com/logo.png
servers:
  - url: https://api.example.com
    description: Production
`)

converter.Generate(
	converter.WithGlobal(),
	converter.WithBaseOpenAPI(baseContent),
)
```

```go
overrideContent := []byte(`
components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
`)

converter.Generate(
	converter.WithGlobal(),
	converter.WithOverrideOpenAPI(overrideContent),
)
```

```go
converter.Generate(
	converter.WithGlobal(),
	converter.WithAllowGET(true),
)
```

```go
converter.Generate(
	converter.WithGlobal(),
	converter.WithContentTypes("json", "proto"),
)
```

--------------------------------

### Retrieve plugin version

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/plugin-entrypoint.md

Check the installed version and build information of the plugin.

```bash
protoc-gen-connect-openapi --version
```

```text
protoc-gen-connect-openapi v0.19.1 (abc1234) @ 2024-01-15T10:30:00Z; go1.21
```

--------------------------------

### Perform a GET request to a Connect service

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/README.md

Example of a raw HTTP GET request to a Connect service endpoint.

```http
> 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!"}
```

--------------------------------

### Checking plugin version

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/plugin-entrypoint.md

Verify the installed version of the plugin.

```bash
protoc-gen-connect-openapi --version
```

--------------------------------

### Enable GET Requests for Idempotent Methods

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/configuration.md

Configure the plugin to generate GET documentation for methods marked with NO_SIDE_EFFECTS.

```yaml
opt:
  - allow-get
```

```proto
service UsersService {
  rpc GetUser(GetUserRequest) returns (User) {
    option idempotency_level = NO_SIDE_EFFECTS;
  }
}
```

```yaml
paths:
  /users/{id}:
    get:
      # GET request allowed
      parameters:
        - name: id
          in: query
    post:
      # POST also allowed
```

--------------------------------

### Generated Path Example

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/connectrpc-paths.md

The resulting path structure after applying a prefix.

```text
POST /api/v1/package.Service/Method
```

--------------------------------

### Implement custom generator option

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/types.md

Example of creating and applying a custom option to modify generator state.

```go
// Creating custom options
customOption := func(g *generator) error {
	g.options.PathPrefix = "/api/v1"
	return nil
}

files, err := converter.Generate(
	converter.WithGlobal(),
	customOption,
)
```

--------------------------------

### gRPC-Gateway Annotations in Protobuf

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/grpcgateway.md

Example Protobuf service definition using gRPC-Gateway annotations to map HTTP methods and paths to gRPC RPCs. This includes options for GET, POST, PUT, DELETE requests, specifying request bodies, and response bodies.

```protobuf
syntax = "proto3";

package io.swagger.petstore.v2;

import "google/api/annotations.proto";
import "google/protobuf/empty.proto";

service PetService {
  rpc GetPetByID(PetID) returns (Pet) {
    option (google.api.http).get = "/pet/{pet_id}";
    option idempotency_level = NO_SIDE_EFFECTS;
  }
  rpc UpdatePetWithForm(UpdatePetWithFormReq) returns (google.protobuf.Empty) {
    option (google.api.http).post = "/pet/{pet_id}";
    option (google.api.http).body = "*";
  }
  rpc DeletePet(PetID) returns (google.protobuf.Empty) {
    option (google.api.http).delete = "/pet/{pet_id}";
  }
  rpc UploadFile(UploadFileReq) returns (ApiResponse) {
    option (google.api.http).post = "/pet/{pet_id}/uploadImage";
    option (google.api.http).body = "*";
  }
  rpc AddPet(Pet) returns (Pet) {
    option (google.api.http).post = "/pet";
    option (google.api.http).body = "*";
  }
  rpc UpdatePet(Pet) returns (Pet) {
    option (google.api.http).put = "/pet";
    option (google.api.http).body = "*";
  }
  rpc FindPetsByTag(TagReq) returns (Pets) {
    option deprecated = true;
    option (google.api.http).get = "/pet/findByTags";
    option (google.api.http).response_body = "pets";
    option idempotency_level = NO_SIDE_EFFECTS;
  }
  rpc FindPetsByStatus(StatusReq) returns (Pets) {
    option (google.api.http).get = "/pet/findByStatus";
    option (google.api.http).response_body = "pets";
    option idempotency_level = NO_SIDE_EFFECTS;
  }
}
```

--------------------------------

### Configure plugin features via YAML

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/README.md

Examples of setting the 'features' option in a configuration file to enable specific RPC and annotation support.

```yaml
opt:
  - features=connectrpc
```

```yaml
opt:
  - features=google.api.http;protovalidate
```

```yaml
opt:
  - features=connectrpc;google.api.http;twirp;gnostic;protovalidate
```

--------------------------------

### Service Tag Formats

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/connectrpc-paths.md

Examples of full and short service tag naming conventions.

```text
mycompany.api.v1.UsersService
```

```text
UsersService
```

--------------------------------

### Generated OpenAPI Path Example

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/connectrpc-paths.md

The resulting OpenAPI path structure generated from the service definition.

```yaml
paths:
  /mycompany.api.v1.UsersService/GetUser:
    post:
      tags:
        - mycompany.api.v1.UsersService
      summary: Gets a user by ID
      description: Gets a user by ID
      operationId: mycompany_api_v1_UsersService_GetUser
```

--------------------------------

### Protobuf Idempotency Configuration

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/connectrpc-paths.md

Example protobuf definition for a method using NO_SIDE_EFFECTS.

```proto
service Users {
  rpc GetUser(GetUserRequest) returns (User) {
    option idempotency_level = NO_SIDE_EFFECTS;
  }
}
```

--------------------------------

### Generated OpenAPI Paths Excerpt

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/connectrpc-paths.md

The generated OpenAPI paths corresponding to the complete service definition example.

```yaml
/mycompany.api.v1.UsersService/ListUsers:
  post:
    tags:
      - mycompany.api.v1.UsersService
    operationId: mycompany_api_v1_UsersService_ListUsers
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ListUsersRequest'

/mycompany.api.v1.UsersService/GetUser:
  get:
    tags:
      - mycompany.api.v1.UsersService
    operationId: mycompany_api_v1_UsersService_GetUser
    parameters:
      - name: encoding
        in: query
        schema:
          type: string
          enum: [json, proto]
      - name: message
        in: query
        schema:
          type: string
  post:
    tags:
      - mycompany.api.v1.UsersService
    operationId: mycompany_api_v1_UsersService_GetUser_Post
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetUserRequest'

/mycompany.api.v1.UsersService/CreateUser:
  post:
    tags:
      - mycompany.api.v1.UsersService
    operationId: mycompany_api_v1_UsersService_CreateUser
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateUserRequest'
    responses:
      '200':
        description: OK
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
```

--------------------------------

### Configure Modern Service with Connect Streaming

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/README.md

Enables JSON and Connect streaming content types with GET request support.

```yaml
opt:
  - content-types=json;connect+json
  - with-streaming
  - allow-get
```

--------------------------------

### Configure buf remote plugin

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/README.md

Use the BSR remote plugin in a buf.gen.yaml file to avoid local installation.

```yaml
version: v2
plugins:
  - remote: buf.build/community/sudorandom-connect-openapi:v0.19.1
    out: gen
    opt:
    - base=example.base.yaml
```

--------------------------------

### Operation ID Formats

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/connectrpc-paths.md

Examples of full and short operation ID naming conventions.

```text
package_Service_Method
```

```text
Service_Method
```

--------------------------------

### Example debug log output

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/plugin-entrypoint.md

Shows the format of structured logs emitted to stderr when debug mode is active.

```text
time=2024-01-15T10:30:00Z level=DEBUG msg="generating file" name=service.proto
time=2024-01-15T10:30:00Z level=INFO msg="generated 2 services" file=service.proto
```

--------------------------------

### Complete Service Protobuf Definition

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/connectrpc-paths.md

A comprehensive example of a service definition including various CRUD operations and message types.

```proto
syntax = "proto3";

package mycompany.api.v1;

service UsersService {
  // List all users with pagination
  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
  
  // Get a specific user by ID
  rpc GetUser(GetUserRequest) returns (User) {
    option idempotency_level = NO_SIDE_EFFECTS;
  }
  
  // Create a new user
  rpc CreateUser(CreateUserRequest) returns (User);
  
  // Update an existing user
  rpc UpdateUser(UpdateUserRequest) returns (User);
  
  // Delete a user
  rpc DeleteUser(DeleteUserRequest) returns (google.protobuf.Empty);
}

message User {
  string id = 1;
  string name = 2;
  string email = 3;
}

message GetUserRequest {
  string user_id = 1;
}

message CreateUserRequest {
  string name = 1;
  string email = 2;
}

message UpdateUserRequest {
  string user_id = 1;
  string name = 2;
  string email = 3;
}

message DeleteUserRequest {
  string user_id = 1;
}

message ListUsersRequest {
  int32 page_size = 1;
  string page_token = 2;
}

message ListUsersResponse {
  repeated User users = 1;
  string next_page_token = 2;
}
```

--------------------------------

### Idempotent RPC (GET)

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/connectrpc-paths.md

Idempotent RPC methods configured with allow-get can be invoked via HTTP GET.

```APIDOC
## GET /package.Service/Method

### Description
Invokes an idempotent RPC method using HTTP GET when configured with allow-get and NO_SIDE_EFFECTS.

### Method
GET

### Endpoint
/package.Service/Method

### Parameters
#### Query Parameters
- **encoding** (string) - Required - Either 'json' or 'proto'.
- **message** (string) - Required - URL-encoded request body.
```

--------------------------------

### Generating OpenAPI from proto

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/plugin-entrypoint.md

Create a sample proto file and run the protoc generator.

```bash
# Create a simple proto file
cat > test.proto << 'EOF'
syntax = "proto3";

package test;

service TestService {
  rpc Test(TestRequest) returns (TestResponse);
}

message TestRequest {}
message TestResponse {}
EOF

# Run protoc
protoc --connect-openapi_out=gen test.proto

# Check output
cat gen/test.openapi.yaml
```

--------------------------------

### Serve Documentation with Redoc

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/README.md

Generate the YAML OpenAPI spec and serve it using the Redoc Docker image.

```bash
# Generate YAML OpenAPI
buf generate

# Serve documentation with Redoc
docker run -p 8080:80 -v $(pwd)/gen:/usr/share/nginx/html:ro redocly/redoc
```

--------------------------------

### Initialize OpenAPI Components

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter-internal.md

Initializes OpenAPI Components with schemas for common types and protocol descriptions. Prepares schema definitions, status codes, and content types.

```go
func initializeComponents(opts options.Options, components *v3.Components) *v3.Components
```

--------------------------------

### Configure via buf.gen.yaml

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/README.md

Recommended configuration method using the buf CLI tool.

```yaml
version: v2
plugins:
  - remote: buf.build/community/sudorandom-connect-openapi:v0.19.1
    out: gen
    opt:
      - format=yaml
      - content-types=json;connect+json
      - allow-get
      - path-prefix=/api/v1
```

--------------------------------

### WithAllowGET

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter.md

Enables GET requests for methods marked with idempotency_level = NO_SIDE_EFFECTS.

```APIDOC
## func WithAllowGET(allowGet bool) Option

### Description
Enables GET requests for methods marked with `idempotency_level = NO_SIDE_EFFECTS` in protobuf. When enabled, such methods will be documented with both POST and GET variants.

### Parameters
- **allowGet** (bool) - Required - Whether to allow GET requests for idempotent methods. Defaults to false.
```

--------------------------------

### Initialize OpenAPI Document

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter-internal.md

Initializes an OpenAPI v3.1 Document with base metadata and empty components. Sets the version to 3.1.0 and prepares the info, paths, and security structures.

```go
func initializeDoc(opts options.Options, doc *v3.Document) *v3.Document
```

--------------------------------

### Configure Documented with Full Metadata

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/README.md

Enables inclusion of service descriptions, proto annotations, and detailed message naming conventions.

```yaml
opt:
  - with-service-descriptions
  - with-proto-annotations
  - fully-qualified-message-names
  - include-number-enum-values
```

--------------------------------

### Programmatic Configuration Override

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/plugin-entrypoint.md

Demonstrates how to override CLI-parsed options programmatically in Go.

```go
// Parameter from CLI: "format=yaml"
opts, _ := options.FromString("format=yaml")

// Override programmatically
opts.Format = "json"

// Result: JSON format used
```

--------------------------------

### Run protoc plugin commands

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/README.md

Execute the plugin via protoc with various options for output format and base file configuration.

```shell
protoc internal/converter/fixtures/helloworld.proto --connect-openapi_out=gen
```

```shell
protoc internal/converter/fixtures/helloworld.proto \
    --connect-openapi_out=gen \
--connect-openapi_opt=format=json
```

```shell
protoc internal/converter/fixtures/helloworld.proto \
    --connect-openapi_out=gen \
    --connect-openapi_opt=base=example.base.yaml,content-types=json
```

--------------------------------

### Configure via protoc Command Line

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/README.md

Direct invocation of the plugin using the protoc compiler.

```bash
protoc service.proto \
    --connect-openapi_out=gen \
    --connect-openapi_opt=format=json \
    --connect-openapi_opt=allow-get \
    --connect-openapi_opt=path-prefix=/api/v1
```

--------------------------------

### Generate OpenAPI documentation for Connect services

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/README.md

Use the protoc plugin to generate standard OpenAPI documentation from a protobuf service definition.

```bash
protoc --connect-openapi_out=gen service.proto
```

--------------------------------

### Configure Elements/Redoc Documentation

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/protocols.md

Enables streaming support and YAML formatting for documentation tools.

```yaml
opt:
  - format=yaml
  - with-streaming
```

--------------------------------

### Idempotent GET Request Path

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/connectrpc-paths.md

The URL structure for methods configured with allow-get and NO_SIDE_EFFECTS idempotency.

```text
GET /package.Service/Method?encoding=json&message={json_encoded_body}
```

--------------------------------

### Configuring via buf

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/plugin-entrypoint.md

Reference the remote plugin in the buf configuration file.

```yaml
# buf.gen.yaml - no installation needed
plugins:
  - remote: buf.build/community/sudorandom-connect-openapi:v0.19.1
```

--------------------------------

### Generating with parameters

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/plugin-entrypoint.md

Run the generator with specific options for format and HTTP method support.

```bash
protoc \
  --connect-openapi_out=gen \
  --connect-openapi_opt=format=json \
  --connect-openapi_opt=allow-get \
  test.proto

cat gen/test.openapi.json
```

--------------------------------

### Invoke plugin via buf

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/plugin-entrypoint.md

Configure and execute the plugin using the buf CLI.

```yaml
# buf.gen.yaml
plugins:
  - local: protoc-gen-connect-openapi
    out: gen
    opt:
      - format=json
```

```bash
buf generate
```

--------------------------------

### Configure Path Prefix

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter.md

Prepends a string to the beginning of each HTTP path in the OpenAPI specification.

```go
converter.Generate(
	converter.WithGlobal(),
	converter.WithPathPrefix("/api/v1"),
)
```

--------------------------------

### WithFiles

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter.md

Adds protobuf files from a protoregistry.Files registry for OpenAPI generation.

```APIDOC
## func WithFiles(files *protoregistry.Files) Option

### Description
Adds protobuf files from a `protoregistry.Files` registry for OpenAPI generation. Services found in these files will be included in the output.

### Parameters
- **files** (*protoregistry.Files) - Required - The registry containing protobuf files to process.
```

--------------------------------

### WithPathPrefix

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter.md

Prepends a string to the beginning of each HTTP path.

```APIDOC
## func WithPathPrefix(prefix string) Option

### Description
Prepends a string to the beginning of each HTTP path in the OpenAPI specification.

### Parameters
- **prefix** (`string`) - Required - Path prefix like `/api/v1`

### Example
```go
converter.Generate(
	converter.WithGlobal(),
	converter.WithPathPrefix("/api/v1"),
)
```
```

--------------------------------

### Run project tests

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/README.md

Commands to execute the test suite for the project.

```shell
go test ./...

# or, if you prefer:
just test
```

--------------------------------

### Generated OpenAPI Paths for Idempotent Methods

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/connectrpc-paths.md

OpenAPI path definition showing both GET and POST variants for an idempotent RPC method.

```yaml
/users/{id}:
  get:
    operationId: GetUser
    parameters:
      - name: encoding
        in: query
        required: true
        schema:
          type: string
          enum: [json, proto]
      - name: message
        in: query
        required: true
        schema:
          type: string
  post:
    operationId: GetUser_Post
    requestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetUserRequest'
```

--------------------------------

### Configure AsyncAPI Channel Template

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter.md

Customizes the WebSocket channel path template using placeholders like {package}, {service}, and {method}.

```go
converter.Generate(
	converter.WithGlobal(),
	converter.WithAsyncAPIChannelTemplate("/stream/{service}/{method}"),
)
```

--------------------------------

### Protobuf with Gnostic OpenAPI v3 Annotations

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/gnostic.md

This protobuf file demonstrates the use of gnostic's OpenAPI v3 annotations to define document information, components, services, and messages.

```protobuf
syntax = "proto3";

package example_with_gnostic;

import "gnostic/openapi/v3/annotations.proto";

option (gnostic.openapi.v3.document) = {
  info: {
    title: "Title from annotation";
    version: "Version from annotation";
    description: "Description from annotation";
    contact: {
      name: "Contact Name";
      url: "https://github.com/sudorandom/protoc-gen-connect-openapi";
      email: "hello@sudorandom.com";
    }
    license: {
      name: "MIT License";
      url: "https://github.com/sudorandom/protoc-gen-connect-openapi/blob/master/LICENSE";
    }
  }
  components: {
    security_schemes: {
      additional_properties: [
        {
          name: "BasicAuth";
          value: {
            security_scheme: {
              type: "http";
              scheme: "basic";
            }
          }
        }
      ]
    }
  }
};

// The greeting service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello(HelloRequest) returns (HelloReply) {
    option idempotency_level = NO_SIDE_EFFECTS;
    option (gnostic.openapi.v3.operation) = {
      deprecated: true,
      security: [
        {
          additional_properties: [
            {
              name: "BasicAuth";
              value: {
                value: []
              }
            }
          ]
        }
      ]
    };
  }
}

// The request message containing the user's name.
message HelloRequest {
  option (gnostic.openapi.v3.schema) = {title: "Custom title for a message"};

  string name = 1 [(gnostic.openapi.v3.property) = {title: "Custom title for a field"}];
}

// The response message containing the greetings
message HelloReply {
  string message = 1;
}

```

--------------------------------

### Configure Connect Protocol

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/protocols.md

Recommended for modern services requiring both simple JSON and streaming capabilities.

```yaml
opt:
  - content-types=json;connect+json
```

--------------------------------

### Invoke plugin via protoc

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/plugin-entrypoint.md

Execute the plugin using the standard protoc command-line interface.

```bash
protoc --connect-openapi_out=gen \
       --connect-openapi_opt=format=json \
       service.proto
```

--------------------------------

### Configure local buf plugin

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/README.md

Use the plugin locally by referencing the binary name in buf.gen.yaml.

```yaml
version: v2
plugins:
  - local: protoc-gen-connect-openapi
    out: gen
    opt:
    - base=example.base.yaml
```

--------------------------------

### Full Version Output Function

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/plugin-entrypoint.md

Function signature for generating the full version string including runtime information.

```go
func fullVersion() string
```

--------------------------------

### Configure Output Path

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/configuration.md

Defines whether to merge all services into a single file or generate one file per protobuf input.

```yaml
plugins:
  - local: protoc-gen-connect-openapi
    opt:
      - path=api.openapi.yaml
```

```yaml
plugins:
  - local: protoc-gen-connect-openapi
    # path not specified - generates per-file
```

--------------------------------

### Configure Service Descriptions

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter.md

Adds service names and their comments to the end of the info.description field.

```go
converter.Generate(
	converter.WithGlobal(),
	converter.WithServiceDescriptions(true),
)
```

--------------------------------

### Configure Service Patterns

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter.md

Limits generation to services matching glob patterns. Supports * and ** wildcards.

```go
converter.Generate(
	converter.WithGlobal(),
	converter.WithServicePatterns([]string{
		"company.api.v1.*Service",
		"company.internal.**",
	}),
)
```

--------------------------------

### Configure multi-protocol API documentation

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/README.md

Specify multiple content types in the configuration to document services supporting various protocols simultaneously.

```yaml
opt:
  - content-types=json;proto;connect+json;grpc;grpc-web
```

--------------------------------

### Project Directory Structure

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/MANIFEST.txt

Displays the file hierarchy for the project documentation.

```text
output/
├── INDEX.md              ← Start here for navigation
├── README.md             ← Project overview
├── configuration.md      ← Parameter reference
├── protocols.md          ← Protocol reference
├── types.md             ← Type definitions
└── api-reference/
    ├── converter.md                 ← Main public API
    ├── converter-internal.md        ← Low-level API
    ├── plugin-entrypoint.md        ← CLI details
    ├── connectrpc-paths.md         ← Connect routing
    └── googleapi-paths.md          ← REST annotations
```

--------------------------------

### API Versioning and Staging Configuration

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/configuration.md

Configures output format, path prefixes, and base files for versioned API generation.

```yaml
version: v2
plugins:
  - local: protoc-gen-connect-openapi
    out: gen
    opt:
      - format=yaml
      - path=api.openapi.yaml
      - path-prefix=/api/v1
      - base=openapi.base.yaml
      - content-types=json;connect+json
      - allow-get
```

--------------------------------

### HTTP Method Annotations

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/googleapi-paths.md

Standard annotations for mapping RPC methods to HTTP verbs.

```proto
option (google.api.http) = {
  get: "/v1/users/{user_id}"
};
```

```proto
option (google.api.http) = {
  post: "/v1/users"
  body: "*"
};
```

```proto
option (google.api.http) = {
  put: "/v1/users/{user_id}"
  body: "*"
};
```

```proto
option (google.api.http) = {
  patch: "/v1/users/{user_id}"
  body: "*"
};
```

```proto
option (google.api.http) = {
  delete: "/v1/users/{user_id}"
};
```

--------------------------------

### Configure Short Service Tags

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter.md

Uses the short service name instead of the fully-qualified name for OpenAPI tags.

```go
converter.Generate(
	converter.WithGlobal(),
	converter.WithShortServiceTags(true),
)
```

--------------------------------

### Configure AsyncAPI File Path

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter.md

Sets the output file path for the generated AsyncAPI v3.1 specification. Only applicable when streaming endpoints are present.

```go
converter.Generate(
	converter.WithGlobal(),
	converter.WithAsyncAPIPath("api.asyncapi.yaml"),
)
```

--------------------------------

### Define Service Documentation in Protobuf

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/connectrpc-paths.md

Include service and method comments in the Protobuf definition to be reflected in the generated OpenAPI specification.

```proto
// Users service manages user accounts and profiles
service UsersService {
  // Gets a user by ID
  rpc GetUser(GetUserRequest) returns (User);
}
```

--------------------------------

### Configure Streaming

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter.md

Includes streaming-specific content types in the generated output.

```go
converter.Generate(
	converter.WithGlobal(),
	converter.WithStreaming(true),
)
```

--------------------------------

### Configure Services

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter.md

Limits generation to specific services by their fully-qualified names.

```go
converter.Generate(
	converter.WithGlobal(),
	converter.WithServices([]protoreflect.FullName{
		"company.api.v1.UsersService",
		"company.api.v1.OrdersService",
	}),
)
```

--------------------------------

### Enable features via configuration

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/START_HERE.md

Specify enabled protocol and annotation support using the features option in a configuration file.

```yaml
opt:
  - features=connectrpc;google.api.http;protovalidate
```

--------------------------------

### Configure Programmatically in Go

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/README.md

Using the converter package directly within a Go application.

```go
content, err := converter.GenerateSingle(
    converter.WithGlobal(),
    converter.WithFormat("json"),
    converter.WithAllowGET(true),
    converter.WithPathPrefix("/api/v1"),
)
```

--------------------------------

### Essential Configuration Options

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/START_HERE.md

Functional options for configuring the generator behavior.

```go
WithFiles(files)                                   // Source files
WithFormat("yaml"|"json")                          // YAML or JSON
WithContentTypes("json", "proto", ...)             // Protocols
WithAllowGET(bool)                                 // GET for idempotent
WithPathPrefix("/api/v1")                          // Prefix paths
WithBaseOpenAPI([]byte)                            // Base document
WithFeatures(Feature...)                           // Enable features
```

--------------------------------

### Define Path Parameters

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/googleapi-paths.md

Use curly braces in the path string to define parameters that bind to request message fields.

```proto
option (google.api.http) = {
  get: "/v1/users/{user_id}/posts/{post_id}"
};
```

--------------------------------

### Generate OpenAPI specifications

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/START_HERE.md

Execute the generation process via the buf CLI.

```bash
buf generate
```

--------------------------------

### Registering the plugin with buf

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/plugin-entrypoint.md

Use the remote plugin path in your buf configuration to integrate the plugin.

```text
buf.build/community/sudorandom-connect-openapi:v0.19.1
```

```yaml
plugins:
  - remote: buf.build/community/sudorandom-connect-openapi:v0.19.1
    out: gen
```

--------------------------------

### ConvertFrom function signature and usage

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter-internal.md

Entry point for reading a serialized CodeGeneratorRequest from an io.Reader.

```go
func ConvertFrom(rd io.Reader) (*pluginpb.CodeGeneratorResponse, error)
```

```go
package main

import (
	"os"
	"google.golang.org/protobuf/types/pluginpb"
	"github.com/sudorandom/protoc-gen-connect-openapi/internal/converter"
)

func main() {
	resp, err := converter.ConvertFrom(os.Stdin)
	if err != nil {
		// Handle error
		message := err.Error()
		renderResponse(&pluginpb.CodeGeneratorResponse{
			Error: &message,
		})
		os.Exit(1)
	}
	
	renderResponse(resp)
}
```

--------------------------------

### Configure Comprehensive Multi-Protocol

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/protocols.md

Enables all supported protocols, resulting in a verbose OpenAPI specification with numerous content type variations.

```yaml
opt:
  - content-types=json;proto;connect+json;connect+proto;grpc;grpc+json;grpc-web;grpc-web+json
  - with-streaming
```

--------------------------------

### Generate OpenAPI and TypeScript Client

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/README.md

Use buf to generate the OpenAPI spec, then pass the resulting file to openapi-generator to create a TypeScript client.

```bash
# Generate OpenAPI from protobuf
buf generate

# Generate TypeScript client
openapi-generator generate \
  -i gen/api.openapi.yaml \
  -g typescript-fetch \
  -o client/
```

--------------------------------

### Configure ProtoAnnotations

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter.md

Adds underlying protobuf type annotations to field descriptions.

```go
converter.Generate(
	converter.WithGlobal(),
	converter.WithProtoAnnotations(true),
)
```

--------------------------------

### Configure Multiple Protocol Support

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/README.md

Enables a wide range of content types including gRPC and Connect protocols with streaming support.

```yaml
opt:
  - content-types=json;proto;connect+json;connect+proto;grpc;grpc+json
  - with-streaming
```

--------------------------------

### Configure AsyncAPI Channel Template

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/configuration.md

Defines the pattern for WebSocket channel paths using placeholders for package, service, and method names.

```yaml
opt:
  - asyncapi-channel-template=/ws/{package}.{service}/{method}
```

```yaml
# Default: /ws/{package}.{service}/{method}
# → /ws/mycompany.api.v1.UsersService/ListUsers

# Simplified: /stream/{service}/{method}
asyncapi-channel-template=/stream/{service}/{method}
# → /stream/UsersService/ListUsers

# Custom: /ws/{package}/{service}/stream/{method}
asyncapi-channel-template=/ws/{package}/{service}/stream/{method}
# → /ws/mycompany.api.v1/UsersService/stream/ListUsers
```

--------------------------------

### Fully Documented Spec Configuration

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/configuration.md

Enables comprehensive documentation features including annotations, service descriptions, and enum values.

```yaml
plugins:
  - local: protoc-gen-connect-openapi
    opt:
      - format=json
      - with-proto-annotations
      - with-service-descriptions
      - include-number-enum-values
      - fully-qualified-message-names
      - short-operation-ids
      - short-service-tags
```

--------------------------------

### Configure Path Prefix

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/connectrpc-paths.md

Use the path-prefix option to prepend a base path to all generated Connect routes.

```yaml
opt:
  - path-prefix=/api/v1
```

--------------------------------

### Configure ProtoNames

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter.md

Uses protobuf field names instead of camelCase JSON names.

```go
converter.Generate(
	converter.WithGlobal(),
	converter.WithProtoNames(true),
)
```

--------------------------------

### Configure generation with functional options

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/START_HERE.md

Use functional options to customize the generation process, such as setting the output format, path prefixes, and enabled features.

```go
converter.Generate(
    converter.WithGlobal(),                           // Source files
    converter.WithFormat("json"),                     // Output format
    converter.WithAllowGET(true),                     // Features
    converter.WithPathPrefix("/api/v1"),              // Path prefix
    converter.WithContentTypes("json", "proto"),      // Protocols
)
```

--------------------------------

### ConvertWithOptions function signature and usage

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter-internal.md

Low-level function for processing protobuf descriptors with specific configuration options.

```go
func ConvertWithOptions(req *pluginpb.CodeGeneratorRequest, opts options.Options) (*pluginpb.CodeGeneratorResponse, error)
```

```go
import (
	"google.golang.org/protobuf/types/descriptorpb"
	pluginpb "google.golang.org/protobuf/types/pluginpb"
	"github.com/sudorandom/protoc-gen-connect-openapi/internal/converter"
	"github.com/sudorandom/protoc-gen-connect-openapi/internal/converter/options"
)

opts := options.NewOptions()
opts.Format = "json"
opts.AllowGET = true

req := &pluginpb.CodeGeneratorRequest{
	FileToGenerate: []string{"myservice.proto"},
	ProtoFile:      []*descriptorpb.FileDescriptorProto{...},
	Parameter:      ptrTo("format=json,allow-get"),
}

resp, err := converter.ConvertWithOptions(req, opts)
```

--------------------------------

### Configure Simple REST API with JSON

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/README.md

Sets the output format to YAML and restricts content types to JSON.

```yaml
opt:
  - format=yaml
  - content-types=json
```

--------------------------------

### WithFormat

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter.md

Sets the output format for the OpenAPI specification.

```APIDOC
## func WithFormat(format string) Option

### Description
Sets the output format for the OpenAPI specification.

### Parameters
- **format** (string) - Required - The output format, either "yaml" or "json". Defaults to "yaml".
```

--------------------------------

### Enable Service Descriptions

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/configuration.md

Includes service names and documentation comments in the generated spec's info.description.

```yaml
opt:
  - with-service-descriptions
```

--------------------------------

### Configure buf.gen.yaml

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/START_HERE.md

Define the plugin configuration within a buf.gen.yaml file to enable OpenAPI generation.

```yaml
version: v2
plugins:
  - local: protoc-gen-connect-openapi
    out: gen
```

--------------------------------

### Define OpenAPI generation options

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/types.md

Configuration structure for OpenAPI generation. Controls output format, enabled features, content types, filtering, and more.

```go
type Options struct {
	// Format is either 'yaml' or 'json' and is the format of the output OpenAPI file(s).
	Format string
	
	// BaseOpenAPI is the file contents of a base OpenAPI file.
	BaseOpenAPI []byte
	
	// OverrideOpenAPI is the file contents of an override OpenAPI file.
	OverrideOpenAPI []byte
	
	// WithStreaming will content types related to streaming (warning: can be messy).
	WithStreaming bool
	
	// AllowGET will let methods with `idempotency_level = NO_SIDE_EFFECTS` to be documented with GET requests.
	AllowGET bool
	
	// ContentTypes is a map of all content types. Available values are in Protocols.
	ContentTypes map[string]struct{}
	
	// Debug enables debug logging if set to true.
	Debug bool
	
	// IncludeNumberEnumValues indicates if numbers are included for enum values in addition to the string representations.
	IncludeNumberEnumValues bool
	
	// WithProtoNames indicates if protobuf field names should be used instead of JSON names.
	WithProtoNames bool
	
	// Path is the output OpenAPI path.
	Path string
	
	// PathPrefix is a prefix that is prepended to every HTTP path.
	PathPrefix string
	
	// TrimUnusedTypes will remove types that aren't referenced by a service.
	TrimUnusedTypes bool
	
	// WithProtoAnnotations will add some protobuf annotations for descriptions
	WithProtoAnnotations bool
	
	// FullyQualifiedMessageNames uses the full path for message types: {pkg}.{name} instead of just the name.
	FullyQualifiedMessageNames bool
	
	// Prevents adding default tags to converted fields
	WithoutDefaultTags bool
	
	// WithServiceDescriptions set to true will cause service names and their comments to be added to the end of info.description.
	WithServiceDescriptions bool
	
	// IgnoreGoogleapiHTTP set to true will cause service to always generate OpenAPI specs for connect endpoints, and ignore any google.api.http options.
	IgnoreGoogleapiHTTP bool
	
	// OnlyGoogleapiHTTP set to true will only generate OpenAPI specs for methods with explicit google.api.http annotations. Methods without google.api.http will be skipped.
	OnlyGoogleapiHTTP bool
	
	// Services filters which services will be used for generating OpenAPI spec.
	Services []glob.Glob
	
	// ShortServiceTags uses the short service name (Name()) instead of the full name (FullName()) for OpenAPI tags.
	ShortServiceTags bool
	
	// ShortOperationIds sets the operationId to shortServiceName + "_" + method short name instead of the full method name.
	ShortOperationIds bool
	
	// WithGoogleErrorDetail will add google error detail to the connect error response.
	WithGoogleErrorDetail bool
	
	// DisableDefaultResponse disables the default 200 response.
	DisableDefaultResponse bool
	
	// EnabledFeatures is a map of enabled features.
	EnabledFeatures map[Feature]bool
	
	// AllowedVisibilities is a map of visibility strings to include.
	AllowedVisibilities map[string]bool

	// ResourceMap is a map of plural resource names to their singular forms.
	ResourceMap map[string]string

	// AsyncAPIPath is the file path where the generated AsyncAPI file will be written.
	AsyncAPIPath string
	
	// AsyncAPIChannelTemplate is the template used to construct the channel path for WebSocket endpoints.
	AsyncAPIChannelTemplate string

	// MessageAnnotator, FieldAnnotator, FieldReferenceAnnotator are custom annotation interfaces
	MessageAnnotator        MessageAnnotator
	FieldAnnotator          FieldAnnotator
	FieldReferenceAnnotator FieldReferenceAnnotator

	// ExtensionTypeResolver resolves protobuf extension types
	ExtensionTypeResolver protoregistry.ExtensionTypeResolver

	// Logger is the structured logger instance
	Logger *slog.Logger
}
```

--------------------------------

### Enable Google Error Details

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter.md

Enables the inclusion of error details from google.rpc's error_details.proto.

```go
converter.Generate(
	converter.WithGlobal(),
	converter.WithGoogleErrorDetail(true),
)
```

--------------------------------

### WithSourceFiles

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter.md

Adds protobuf files as dependencies without generating OpenAPI specs for them.

```APIDOC
## func WithSourceFiles(files *protoregistry.Files) Option

### Description
Adds protobuf files as dependencies without generating OpenAPI specs for them. Useful for providing type definitions that services depend on.

### Parameters
- **files** (*protoregistry.Files) - Required - The registry containing dependency files.
```

--------------------------------

### Key Plugin Types

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/START_HERE.md

Core type definitions used throughout the plugin configuration.

```go
type Feature string
type Options struct { /* 25+ fields */ }
type Option func(*generator) error
```

--------------------------------

### Configure Debug

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter.md

Enables debug logging to standard error.

```go
converter.Generate(
	converter.WithGlobal(),
	converter.WithDebug(true),
)
```

--------------------------------

### Check for matching services

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter-internal.md

Determines if a file descriptor contains services that align with the provided configuration patterns.

```go
func hasMatchingService(opts options.Options, fd protoreflect.FileDescriptor) bool
```

--------------------------------

### Enable Streaming Protocols

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/protocols.md

Configures the generator to include streaming support and specific content types.

```yaml
opt:
  - with-streaming
  - content-types=json;connect+json;connect+proto
```

--------------------------------

### Configure Simple REST API

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/protocols.md

Use this configuration for standard HTTP clients, browsers, and tools like Postman or curl.

```yaml
opt:
  - content-types=json
```

--------------------------------

### Version Information Retrieval

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/plugin-entrypoint.md

Function signature for extracting build information from the Go debug package.

```go
func getVersionInfo() (version, commit, date string)
```

--------------------------------

### WithGlobal

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter.md

Convenience function that uses protoregistry.GlobalFiles as the source of protobuf files.

```APIDOC
## func WithGlobal() Option

### Description
Convenience function that uses `protoregistry.GlobalFiles` as the source of protobuf files. Equivalent to `WithFiles(protoregistry.GlobalFiles)`.
```

--------------------------------

### Configure generator options

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/INDEX.md

Essential functional options for customizing the OpenAPI generation process.

```go
WithFiles(files)                    // Source protobuf files
WithGlobal()                        // Use global registry
WithFormat("json"|"yaml")           // Output format
WithContentTypes("json", "proto")   // Protocols to include
WithAllowGET(true)                  // GET for idempotent
WithBaseOpenAPI([]byte)             // Base document
WithPathPrefix("/api/v1")           // Path prefix
```

--------------------------------

### Configure Protocol Features

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/configuration.md

Enable specific protocol and annotation systems using the features option.

```yaml
opt:
  - features=connectrpc;google.api.http;gnostic;protovalidate
```

```yaml
# Only Connect RPC
opt:
  - features=connectrpc

# Connect + Gnostic + Protovalidate (no gRPC-Gateway)
opt:
  - features=connectrpc;gnostic;protovalidate

# Everything enabled
opt:
  - features=connectrpc;google.api.http;twirp;gnostic;protovalidate
```

--------------------------------

### Configure AsyncAPI Path

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/configuration.md

Specifies the output file path for the generated AsyncAPI v3.1 specification.

```yaml
opt:
  - asyncapi-path=api.asyncapi.yaml
```

--------------------------------

### Import Google API Annotations

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/googleapi-paths.md

Required import statement for using google.api.http annotations in proto files.

```proto
import "google/api/annotations.proto";
```

--------------------------------

### Generate JSON OpenAPI specs for client generation

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/README.md

Configure the plugin to output JSON format, which is compatible with tools like openapi-generator for client code generation.

```bash
protoc --connect-openapi_out=gen \
       --connect-openapi_opt=format=json service.proto

# Then use openapi-generator to generate clients
```

--------------------------------

### Define Singleton Resource Path

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/googleapi-paths.md

Pattern for identifying a single resource instance in a RESTful path.

```text
/v1/resources/{resource}
```

--------------------------------

### WithProtoNames

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter.md

Uses protobuf field names instead of camelCase JSON names.

```APIDOC
## func WithProtoNames(enabled bool) Option

### Description
Uses protobuf field names instead of camelCase JSON names in the generated OpenAPI schemas.

### Parameters
- **enabled** (bool) - Required - Whether to use protobuf field names (Default: false)

### Example
```go
converter.Generate(
	converter.WithGlobal(),
	converter.WithProtoNames(true),
)
```
```

--------------------------------

### Enable Twirp Support in buf.gen.yaml

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/twirp.md

Configure your buf.gen.yaml to enable the 'twirp' feature for protoc-gen-connect-openapi. This ensures OpenAPI specifications are generated for your Twirp services.

```yaml
version: v2
plugins:
  - remote: buf.build/community/sudorandom-connect-openapi:v0.19.1
    out: gen
    opt:
      - features=twirp
```

--------------------------------

### Generate OpenAPI files in Go

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter.md

Use the Generate function to produce multiple OpenAPI specification files based on provided options.

```go
func Generate(opts ...Option) ([]*pluginpb.CodeGeneratorResponse_File, error)
```

```go
package main

import (
	"fmt"
	"google.golang.org/protobuf/reflect/protoregistry"
	"github.com/sudorandom/protoc-gen-connect-openapi/converter"
)

func main() {
	files, err := converter.Generate(
		converter.WithFiles(protoregistry.GlobalFiles),
		converter.WithFormat("yaml"),
		converter.WithAllowGET(true),
	)
	if err != nil {
		panic(err)
	}
	
	for _, file := range files {
		fmt.Printf("Generated: %s\n", file.GetName())
		fmt.Printf("Content: %s\n", file.GetContent())
	}
}
```

--------------------------------

### WithServiceDescriptions

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/converter.md

Adds service names and comments to the info.description field.

```APIDOC
## func WithServiceDescriptions(enabled bool) Option

### Description
Adds service names and their comments to the end of the `info.description` field.

### Parameters
- **enabled** (`bool`) - Required - Whether to add service descriptions (default: false)

### Example
```go
converter.Generate(
	converter.WithGlobal(),
	converter.WithServiceDescriptions(true),
)
```
```

--------------------------------

### Configure Browser-Compatible Streaming

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/protocols.md

Enables both simple JSON and browser-based streaming using the gRPC-Web protocol.

```yaml
opt:
  - content-types=json;grpc-web;grpc-web+json
```

--------------------------------

### Connect Protocol Path Structure

Source: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/_autodocs/api-reference/connectrpc-paths.md

The standard URL scheme for Connect RPC methods.

```text
POST /package.Service/Method
```
Tokens:
Raw