reliant-labs/forge/api-openapi

OpenAPI Specs from Proto

Forge can emit one OpenAPI 3 yaml per service alongside its Connect RPC handlers. The spec is generated by `protoc-gen-connect-openapi` during forge generate, scoped to each proto/services/<svc>/ so each service gets its own self-contained file under openapi/.

This is a projection of proto — every shape in the yaml is derived from the proto file. Hand-editing the yaml is never the right answer; edit the proto and regenerate.

Enable it

Two steps:

1. Install the plugin (once per machine):

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

forge generate errors with this exact command in the message if the binary isn't on PATH when api.openapi: true.

1. Flip the flag in forge.yaml:

``yaml api: openapi: true ``

Then run forge generate. One spec per service lands under openapi/<service>.yaml at the project root.

The flag is off by default so existing projects regenerate byte-identically until they opt in.

Where the spec lands

<project root>/
  openapi/
    <service-a>.yaml
    <service-b>.yaml
    ...

The output filename matches the proto file's base name. For the canonical layout proto/services/users/v1/users.proto you get openapi/users.yaml.

Commit the openapi/ directory if you want CI to fail when the spec drifts from the proto. Add it to .gitignore if you treat it as a build artifact.

Feeding it to consumers

The yaml is a standard OpenAPI 3 document, so anything that speaks OpenAPI 3 works. Some common destinations:

openapi-generator for client SDKs

# TypeScript fetch client
openapi-generator-cli generate \
  -i openapi/users.yaml \
  -g typescript-fetch \
  -o sdk/users-ts
 
# Python client
openapi-generator-cli generate \
  -i openapi/users.yaml \
  -g python \
  -o sdk/users-py

Postman / Insomnia import

Drag openapi/<svc>.yaml into Postman's "Import" dialog (File → Import → Upload Files). Postman auto-generates a collection with one request per RPC, named after the proto methods.

ChatGPT function-calling / agent toolchains

Both OpenAI's GPTs and Anthropic's tool-use accept OpenAPI 3 specs directly. Paste the contents of openapi/<svc>.yaml into the GPT "Actions" config, or load it as an Anthropic tools definition (the OpenAPI parser is built into most agent frameworks: LangChain OpenAPIToolkit, LlamaIndex OpenAPIToolspec, etc.).

Documentation portals

• ReadMe.io / Stoplight / Redocly: upload openapi/<svc>.yaml

as the API definition. The portal renders try-it consoles, code samples per language, and a search index from the spec.

• swagger-ui (self-hosted): point url: at the yaml. Works as a

static asset behind any web server.

Server stubs in other languages

openapi-generator also emits server skeletons for Spring, FastAPI, Express, etc. — useful when a non-Go team needs to mock the same API shape for contract testing.

How it interacts with your buf.gen.yaml

Forge runs the OpenAPI plugin via a synthesized buf.gen.openapi.yaml written and removed per forge generate run. Your hand-edited buf.gen.yaml is the source of truth for Go stubs and isn't touched by the OpenAPI step.

This means you can freely customize buf.gen.yaml (add other plugins, switch between local: and remote:, etc.) without affecting OpenAPI generation. The flag in forge.yaml controls whether the step runs at all.

CI integration

Two common shapes:

1. Spec-as-artifact: commit openapi/ and let the verify-generated

job in .github/workflows/ci.yml catch drift — it already runs forge generate and fails on an uncommitted diff.

1. Spec-as-build-output: don't commit openapi/; have a publish

job run forge generate and upload to a documentation portal (ReadMe.io webhook, S3 bucket behind Redocly, etc.).

For shape 1, the proto-breaking gate (.github/workflows/proto-breaking.yml) already catches breaking proto changes before they're merged — the OpenAPI diff is mostly a sanity check that the spec actually rebuilt.

Common gotchas

• `protoc-gen-connect-openapi not found on PATH` — install it

with go install github.com/sudorandom/protoc-gen-connect-openapi@latest, then make sure $(go env GOBIN) (default $HOME/go/bin) is on your PATH.

• Spec doesn't update after a proto edit — forge generate

must succeed. If buf fails earlier (e.g. invalid proto syntax), the OpenAPI step never runs.

• Different filename than expected — the plugin uses the proto

file's base name, not the service name. Rename the proto if you want a different yaml filename, or post-process under your own build step.

• `api.openapi: true` but no spec emitted — check that

the project is a service (codegen derives from that). The OpenAPI step is codegen-gated since it shares proto inputs with the Go-stub buf step.

• Need REST/JSON transcoding, not just docs — that's a separate

feature (api.rest:) owned by a different forge surface. The OpenAPI flag only emits documentation; it does not change the runtime transport.