Swagger Api Synchronization
# Set up an OpenAPI spec-sync workflow in this project I want the same backend-spec workflow I use in another repo: a script that diffs the live OpenAPI spec against a local snapshot and writes a **frontend-oriented**…
Open the source (opens github.com) https://github.com/f/prompts.chat
What it is
Prompts from nurullah.
The problem it solves and who it suits haven't been reviewed by InnerVault. The description above is the source's own.
The prompt
# Set up an OpenAPI spec-sync workflow in this project
I want the same backend-spec workflow I use in another repo: a script that diffs the live
OpenAPI spec against a local snapshot and writes a **frontend-oriented** change report, plus a
`/api-sync` slash command that turns that report into a phased plan.
Fill these in from the repo before you start (ask me only if you can't work it out):
- **Spec source**: find it yourself — see Part 0. Don't ask me for the URL until you've looked.
Whatever you find becomes the script's default, overridable via an `OPENAPI_URL` env var.
- **Snapshot path**: `api-spec/openapi.yaml` · **Report path**: `api-spec/CHANGES.md`
- **Source root to cross-reference**: `src/` (adjust to this repo's layout)
- **Response-validation library**: zod (adjust if this repo uses something else)
- **Snapshot in git?** Keep the yaml **gitignored** (too large/noisy for history) but **commit
`CHANGES.md`** — the generated report is the durable record of what changed and when. Also
ignore `api-spec/openapi-*.yaml` and `api-spec/CHANGES-*.md` (dated manual archives).
Read this repo first (package manager, script conventions, how API calls and response schemas are
written) and match its style. Don't invent paths — grep for the real ones.
---
## Part 0 — find the spec before you write anything
Do this first and tell me what you found. Don't guess a URL, and don't ask me until this comes up
empty.
**1. The docs — cheapest place, and usually right.** `README.md`, `CLAUDE.md`,
`AGENTS.md`, `CONTRIBUTING.md`, anything under `docs/`, `.github/`, `.cursor/rules/`, a
`*.http`/`*.rest` scratch file, or a wiki checkout. The URL is often in prose ("API docs:
…/swagger"), in a setup step, or next to the backend repo link:
```bash
grep -rniE 'swagger|openapi|api-?docs|redoc|\/v3\/api-docs' --include='*.md' --include='*.mdx' --include='*.txt' --include='*.http' --include='*.rest' . | grep -v node_modules
```
Two gotchas: a **Swagger UI link** (`…/swagger-ui/index.html`, `…/docs`, `…/redoc`) is an HTML
page, not the spec — derive the machine URL from it (`/swagger-ui/index.html` →
`/v3/api-docs`, `/docs` → `/openapi.json`, `/redoc` → the `spec-url` in its HTML) and verify with
curl. And a docs URL may be **stale** — confirm it answers before adopting it, and tell me if the
README points somewhere dead.
**2. A spec file already in or near the repo** — someone usually vendored one:
```bash
find . -path ./node_modules -prune -o -iregex '.*\(swagger\|openapi\|api-docs\).*\.\(ya?ml\|json\)' -print
git ls-files | grep -iE 'swagger|openapi|api-docs'
```
Also check `node_modules/.cache/`, `.next/cache/`, `dist/`, `build/`, `coverage/` and any
gitignored `api/`, `api-spec/`, `docs/`, `schemas/` folder — a previous codegen run often left a
copy there. A stale cached copy is still useful: it's a **baseline to seed the snapshot with**,
so the first real diff is meaningful instead of "everything is new". If you find one, say how
old it is (`git log -1` / file mtime) before deciding to trust it.
**3. A generator config that already names the source** — this is the highest-signal hit, because
it points at whatever URL or path the team actually uses:
```bash
grep -rniE 'openapi|swagger|api-docs' --include='*.json' --include='*.ts' --include='*.js' --include='*.mjs' --include='*.yaml' --include='*.yml' --include='.env*' --include='Makefile' --include='*.sh' -l . | grep -v node_modules
```
Look specifically for: `openapi-typescript` / `orval.config.*` / `kubb.config.*` /
`swagger-typescript-api` / `@hey-api/openapi-ts` config, an `openapi`-ish npm script in
package.json, a `.env*` API base URL, `docker-compose.yml` service URLs, CI workflow steps, or a
committed generated client whose header comment cites its source spec.
**4. Derive it from the API base URL.** If you only find a base URL, probe the conventional paths
for that backend's framework before asking me — FastAPI `/openapi.json`, Spring/springdoc
`/v3/api-docs` (+ `.yaml`), ASP.NET `/swagger/v1/swagger.json`, NestJS `/api-json`, Rails/rswag
`/api-docs/v1/swagger.yaml`, plus plain `/openapi.yaml` and `/swagger.json`:
```bash
curl -sS -o /dev/null -w '%{http_code} %{content_type} %{url_effective}\n' <BASE>/openapi.json
```
Report which ones answered. If they all need auth, say so — don't bake a token into the script.
**5. Nothing works?** Then ask me, and tell me what you ruled out.
### If the spec isn't reachable over HTTP
Don't force the fetch design. Make the source a single `SPEC_SOURCE` that may be **a URL, a local
path, or a shell command** (e.g. the backend repo's own `make openapi`, or a sibling checkout's
generated file), resolved in that order: `--to <file>` flag → `OPENAPI_URL` env → the default you
discovered. Everything downstream — diff, report, snapshot — is unchanged. Say in `CLAUDE.md`
which one this repo uses and how to refresh it.
## Part 1 — `scripts/sync-api.mjs`
A single dependency-light Node ESM script (`js-yaml` is the only new dep; use the repo's package
manager). Flags:
```
node scripts/sync-api.mjs fetch remote → diff vs snapshot → write report + overwrite snapshot
node scripts/sync-api.mjs --check diff only, snapshot untouched, exit 1 if it drifted (CI-friendly)
node scripts/sync-api.mjs --from <file> diff against <file> instead of the snapshot
node scripts/sync-api.mjs --to <file> treat <file> as "remote" instead of fetching (offline)
node scripts/sync-api.mjs --json also print the raw diff as JSON on stdout
```
Add `"sync:api": "node scripts/sync-api.mjs"` to package.json.
**If no snapshot exists yet**: write the fetched spec as the snapshot, print "seeded — re-run after
the backend ships to see a diff", exit 0. Never report the whole API as "new". Exception: if Part 0
turned up an older cached/vendored spec, seed the snapshot from **that** instead and run a real
diff against the live spec on the first run — tell me the cached copy's date so I know what…
Written by the prompts.chat (CC0 prompt collection) community (nurullah). Not tested by InnerVault.
How to get it
Setup steps: not applicable.
Related
-
This is a test prompt created to verify API authentication.
-
API Design Expert Agent Role
Prompts# API Design Expert You are a senior API design expert and specialist in RESTful principles, GraphQL schema design, gRPC service definitions, OpenAPI specifications, versioning strategies, error handling patterns…
-
API Tester Agent Role
Prompts# API Tester You are a senior API testing expert and specialist in performance testing, load simulation, contract validation, chaos testing, and monitoring setup for production-grade APIs. ## Task-Oriented Execution…
-
API Contract Diff Reviewer
Prompts--- name: api-contract-diff-reviewer description: Review API/OpenAPI diffs for breaking changes and draft a migration checklist for consumers. --- # API Contract Diff Reviewer When the user pastes an API diff, OpenAPI…
-
API Rate Limit Policy Simulator
Prompts--- name: api-rate-limit-policy-simulator description: Simulates API rate limits before you ship them - token bucket, fixed window, sliding log and sliding counter, per client, endpoint, tier or global - against…
-
Act as a Developer Experienced in Unofficial APIs. You are tasked with creating an unofficial Instagram API to access certain features programmatically. Your task is to: - Design a system that can interact with…