OpenAPI sync

Most modern API frameworks already produce an OpenAPI document — Django + DRF via drf-spectacular, FastAPI natively, Spring via SpringDoc, Rails via rswag, NestJS via @nestjs/swagger. OpenAPI sync lets Stoney consume that document on every push to your repo, so the routes and types your framework knows about become the routes and types Stoney enforces rules against.

Two minutes to wire up. One workflow file, one secret. After that, every merge to your default branch refreshes Stoney’s view of your API automatically.

When to use this

OpenAPI sync is the right path when all of these are true:

Your stack isn’t Next.js. (Next.js users don’t need OpenAPI sync — Stoney’s static extractor handles app/api/**/route.ts directly.)
Your framework produces an OpenAPI 3.0, 3.1, or Swagger 2.0 document. Either built-in (FastAPI) or via a passive generator (drf-spectacular, SpringDoc, etc.).
Your code lives in a GitHub repo with Actions enabled.

If your stack doesn’t fit (raw JsonResponse-style Django, a custom HTTP layer, no schema generator), the recorder is the universal fallback — it catches actual traffic and works regardless of framework.

How it works


  push to main
       │
       ▼
  CI workflow runs
       │
       ▼
  framework's OpenAPI generator emits schema.json
       │
       ▼
  one-line curl uploads schema.json to Stoney
       │
       ▼
  Stoney parses, persists routes, generates rule suggestions
       │
       ▼
  rules appear in your dashboard within ~3 minutes

The upload is authenticated via a per-install Bearer token (stored as a GitHub Actions secret on your repo). Stoney stores only a hash of the token — the raw value is shown once at install time and is never recoverable. Lose it, revoke the install and create a new one.

Setting it up

Open Settings → Connections → OpenAPI sync in your Stoney dashboard.
Click New OpenAPI sync. Name it something clear like owner/repo · production.
Stoney generates a token. Copy it — this is the only time you’ll see the raw value.
Pick your framework. Stoney shows the exact files to add to your repo:
- A workflow file at .github/workflows/stoney-openapi-sync.yml
- For Django + DRF: a drf-spectacular dependency add and a settings.py snippet
- A magic link to your repo’s secret-settings page where you paste the token
Add the secret (STONEY_TOKEN) to your GitHub repo’s Actions secrets.
Commit + push the workflow file. The first sync runs immediately.

After the first run, you’ll see your routes appear in the dashboard within a couple minutes — first the route inventory, then Claude-generated rule suggestions a minute or two after that.

Supported frameworks

Framework	Setup notes
Django + DRF	Adds `drf-spectacular` (passive — no runtime impact on your API) and a single setting. Most idiomatic DRF codebases extract cleanly.
FastAPI	Zero code changes. The workflow boots your app, fetches `/openapi.json`, uploads.
Spring Boot	Use SpringDoc (`org.springdoc:springdoc-openapi-starter-webmvc-ui`); workflow runs `./mvnw springdoc-openapi:generate`.
Rails	Use rswag (`bundle exec rake rswag:specs:swaggerize`).
NestJS	Use `@nestjs/swagger`; bootstrap script exports the spec.
Everything else	Generic workflow template: whatever your generator produces, the upload step is portable.

If your framework has a maintained OpenAPI generator (most do), it’ll work. The Other framework option in the create modal gives you a workflow template you can drop your generator command into.

Common questions

Is the spec file persisted anywhere? We persist the derived rules, the route inventory, and the diff between syncs (for drift detection). We don’t store your full spec; it’s transient on our server during the parse step.

Does this break my CI? No. The upload step runs after your existing checks and only WRITES to Stoney. If the upload fails (token revoked, Stoney down), it logs an error but doesn’t fail your CI run — unless you want it to, in which case remove the -f flag from the curl command.

Can I sync from multiple environments? Yes — create one install per environment (production, staging, etc.). Each gets its own token; routes get tagged with the environment label in the dashboard.

Can I rotate the token? Yes. Revoke the install in Settings → Connections → OpenAPI sync, create a new one, replace the secret in your repo. Old token stops authenticating immediately.

Do I still need GitHub App / StoneyBot installed? For OpenAPI sync alone, no — the workflow runs in your CI and authenticates via the token. But you’ll want StoneyBot installed if you also want pre-merge rule checks on your PRs.

Where does the token live in CI? As a repository-level GitHub Actions secret named STONEY_TOKEN. It’s never exposed in workflow logs. The curl step references it via ${{ secrets.STONEY_TOKEN }} and exports it into the step’s env before invoking curl.