Skip to content
Back to skills

Api Openapi

BSecurity

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).

  • 10 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added November 13, 2026
developmenttypescriptpythongobashexpressfastapispringtestinggitapi

Works with

  • cli
  • api

Security analysis

B75/100
  • criticalSends environment variables or credentials to an external URL

Pro shows the line behind each finding and how to fix it

Scanned November 14, 2026

npx -y skills add reliant-labs/forge --skill api-openapi --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Api Openapi?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Api Openapi
[![Security: B — Skills Directory](https://www.skillsdirectory.com/api/skills/reliant-labs-api-openapi/badge)](https://www.skillsdirectory.com/skills/reliant-labs-api-openapi)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
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.

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in development →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.