protoc-gen-openapi

A protoc compiler plugin that converts gRPC service definitions (protobuf) into OpenAPI v3.1 specifications. Designed to pair with Envoy's GrpcJsonTranscoder: every compiler option that affects wire format has a corresponding Envoy filter option, so the generated OAS document describes what Envoy will actually emit. The plugin compiles to a native binary via GraalVM so it can be used directly in a protoc invocation without a JVM on PATH.

The plugin runs in two modes that can be mixed within a single proto file:

• Convention-based — no engine annotations required. The plugin derives operations, path parameters, and request/response shapes from standard google.api.http bindings (or via autoMapping=true), and pulls info.title from the service name and info.version from the version option. See the conventions example for a complete working sample.
• Annotation-based — import engine/protoc/openapi/annotations.proto and attach engine annotations to add or override anything the conventions can't express: explicit info, tags, security schemes, per-field schema constraints, etc. See the model README for the full annotation list and the examples for richer illustrations.

The plugin executable must be protoc-gen-openapi on PATH (or pointed at explicitly — see the Gradle examples below). Options are passed as --openapi_out=<comma-separated-options>:<outdir>.

Configure the protobuf-gradle-plugin to invoke protoc-gen-openapi as a code-generation plugin.

plugins {
    id("com.google.protobuf") version "0.9.6"
}

// optional: include the annotations in your project
dependencies {
    protobuf("com.engine:protoc-gen-openapi-model:<version>")
}

protobuf {
    plugins {
        create("openapi") {
            // path to the native binary; or set `artifact = ...` once the published artifact is available
            artifact = "com.engine:protoc-gen-openapi:<version>"
        }
    }
    generateProtoTasks {
        all().all {
            plugins {
                create("openapi") {
                    option("version=1.0.0")
                    option("autoTagServices=true")
                    // other options as desired
                }
            }
        }
    }
}

# optional one-time: download and extract the model protos
curl -L -o protoc-gen-openapi-model-protos.zip \
  https://github.com/engine-public/protoc-gen-openapi/releases/download/<version>/protoc-gen-openapi-model-protos.zip
unzip -d build/proto/openapi-model protoc-gen-openapi-model-protos.zip

protoc \
  --proto_path=optional/path/to/extracted/model/protos \
  --proto_path=path/to/your/protos \
  --openapi_out=autoTagServices=true,otherOptionsAsDesired:./build/openapi \
  src/main/proto/example/v1/service.proto

All options are defined on ProtocGenOpenAPI.Options. Click the option name to jump to its KDoc for full semantics, precedence rules, and Envoy interoperability notes.

Enum-valued options accept their values case-insensitively.

The plugin reads the body field of every google.api.http annotation and maps it to OpenAPI as specified in google/api/http.proto — the same semantics enforced at runtime by Envoy's gRPC-JSON transcoder. The three modes are identical across all five verbs (GET, POST, PUT, PATCH, DELETE):

Auto-derived query parameters use the field's JSON name by default (or the snake_case proto name when preserveProtoFieldNames is set), recurse into nested messages with dotted names (?address.city=…), and emit style=form, explode=true for repeated scalars. Repeated message and map fields are skipped with a WARN log since OpenAPI has no faithful query-string representation for them. Each parameter's schema carries the field's own (engine.protoc.openapi.field) annotation (constraints, format, enum, …) merged on top of its proto-derived type, so a query parameter advertises the same constraints the field declares everywhere else.

When a method also declares (engine.protoc.openapi.parameters) entries, those manual declarations win for any field they cover and a WARN log records the overlap. A field is treated as covered when a manual parameter's name matches its proto name, its JSON name, or — for nested fields — its dotted name (address.city); manual entries that reference a reusable component via $ref are matched by the referenced component's declared name. Two coverage cases cannot be detected and may surface as duplicate parameters: a $ref the plugin cannot resolve locally (a remote/relative $ref, or one whose component is itself a $ref), and a nested field bound to the URL with a dotted placeholder such as {address.city} (the path-template parser only recognises single-segment {var} placeholders). Declare the overlapping field with an inline parameter, or move it into the request body, to avoid the duplicate. Worked examples live in examples/src/envoy/ (live Envoy round-trip tests) and examples/src/complete/ (snapshot coverage of every verb/body combination, plus manual-override precedence).

• engine-public/protoc-utils — shared protoc plugin utilities (descriptor wrappers, comment parsing, parameter handling) and the recorder plugin used by this project's example suite.

See CONTRIBUTING.md for build commands, the native-image / reflection metadata workflow, and the PR process.