Emit OpenAPI 3 specs from your proto services as a buf pipeline step — opt-in via `api.openapi: true` in forge.yaml. The spec is a projection of proto, so the proto file stays the single source of truth. Also — bring your own OpenAPI 3 spec: declare it as a `forge.API` and forge validates and lists it (what works today, and what does not yet).
Installs into .claude/skills of the current project.
Sponsors
SSkills DirectorySkills Directory
Know which skills are safe — weekly.
SSkills DirectorySkills Directory
Is that skill safe to install?
Are you the author of Api Openapi?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/reliant-labs-api-openapi)
---
name: api-openapi
description: Emit OpenAPI 3 specs from your proto services as a buf pipeline step — opt-in via `api.openapi: true` in forge.yaml. The spec is a projection of proto, so the proto file stays the single source of truth. Also — bring your own OpenAPI 3 spec: declare it as a `forge.API` and forge validates and lists it (what works today, and what does not yet).
---
# 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`](https://github.com/sudorandom/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.
## Bring your OpenAPI spec (an API that is not proto)
An API whose contract is an OpenAPI document you already have is declared as
a `forge.API` in the env (`deploy/kcl/<env>/main.k`):
```python
apis = [forge.API {
name = "billing"
kind = "openapi"
spec = "api/openapi.yaml" # repository-relative, YAML or JSON
base_path = "/billing" # optional, starts with "/"
database = "default" # optional: a database the env declares
}]
```
**What works today (~10 min):**
- **Validation when the env loads.** Every command that loads the env reads the
spec. It must be a file whose top-level `openapi` is `3.x`. A Swagger 2
document is refused with "convert it to OpenAPI 3" (`npx swagger2openapi`
does it). A missing file, a missing version or another version are refused
too, naming the API.
- **Listing.** `forge project audit --json`, `.categories.resources.details.apis[]`,
lists every API with `origin` `kcl` and the envs that declare it. A project
with proto services and no proto API declared gets one derived:
`{name: <project>, kind: proto, spec: proto, origin: derived}`.
- KCL checks the rest: `kind` is `proto` or `openapi`, names are unique, `spec`
is inside the repository, and `database` names a declared database.
**Not yet:** forge generates nothing from an OpenAPI spec, and serves,
routes and lints nothing from it. No handlers, clients, hooks, mocks or
contract tests come from it. Today the declaration is groundwork: it records
which APIs the project has, and later features read it from there.
## 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`.
2. **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
```bash
# 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.
2. **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.