`src/openapi.ts` is a hand-maintained spec with no parity check against the actual routers

[Jagadeeshftw]

Priority: Medium  ·  Area: API documentation / contract testing  ·  Est. effort: 6–9 h

📌 Problem

src/openapi.ts hand-declares the API surface served at GET /api/v1/openapi.json, with a literal paths object listing entries such as /api/v1/info, /api/v1/audit, /api/v1/liquidity and /api/v1/liquidity/withdraw.

The real surface lives in five routers under src/routes/ — anchors.ts, liquidity.ts, metrics.ts, quote.ts, settlements.ts.

Nothing checks that these agree. The two are maintained by hand, independently, so they drift in both directions:

• A route added without a spec entry is undocumented — consumers never learn it exists.
• A spec entry whose route was removed or renamed is worse: it documents an endpoint that 404s, and consumers write code against it.

Response shapes drift the same way, and are harder to notice than paths.

🎯 Design decision required

State and defend:

1. Generate or verify? Generating the spec from the routers removes drift structurally but requires route metadata and is a larger change. A parity test is cheaper and catches drift at CI time without restructuring. Argue which fits this codebase now.
2. Depth. Paths only, or paths plus methods plus response shapes? Path-only parity is easy and catches the worst cases; shape parity catches more but needs a source of truth for shapes. Say where you drew the line and why.
3. Existing drift. Run your check first — there is very likely drift today. Fix it in this PR or list it, but do not let the check pass by encoding the drift as expected.

🧩 Requirements and context

• Report the current drift before fixing anything. That inventory is the first deliverable.
• The check must run in CI and fail the build on drift.
• Do not change the API surface to make the spec match — if a route is missing from the spec, add it to the spec; if the spec documents something that does not exist, remove it from the spec (and say so, in case its absence is the real bug).
• src/openapi.test.ts exists — extend it rather than starting a parallel suite.
• Keep GET /api/v1/openapi.json's served output valid OpenAPI; validate it.

🛠️ Suggested execution

1. Enumerate every route the five routers actually mount, and diff against openapi.ts. Paste the result.
2. Implement your chosen mechanism.
3. Resolve existing drift.
4. Wire the check into CI and prove it fails on a deliberately unregistered route.
5. Validate the served document against the OpenAPI schema.

✅ Acceptance criteria

• The PR opens with the current path/method drift inventory.
• A check fails when a router mounts a route absent from the spec, and vice versa.
• The check runs in CI, demonstrated failing on a deliberate mismatch.
• Existing drift is resolved, not encoded as expected.
• The served document validates as OpenAPI.
• npm run lint, npm run build and npm test pass.

🚫 Out of scope

• Changing the API surface itself.
• Generating client SDKs.
• Rewriting route handlers.

🧪 Verification

npm ci
npm test src/openapi.test.ts
npm run lint && npm run build && npm test

📤 What your PR must include

1. The drift inventory.
2. Your generate-vs-verify decision and depth choice.
3. How you resolved each drift item.
4. A link to a run failing on a deliberate mismatch.
5. Closes #<n>.

🔒 Security notes

An OpenAPI document is often treated as the authoritative inventory of a service's attack surface — it is what a reviewer or scanner enumerates. An endpoint that exists but is absent from the spec is therefore an endpoint nobody audits, and on this service the routers include liquidity withdrawal and settlement creation. Parity between the documented and the real surface is a precondition for any meaningful API security review.

📋 Guidelines

• Minimum 95% test coverage on changed lines
• Clear documentation
• Timeframe: 96 hours from assignment
• One logical change per commit; no merge commits

---

💬 Join our community

Working on this, or want to sanity-check your approach before you start? Come and ask — the maintainers are there and happy to help.

Telegram: https://t.me/Grainlify

[martinshub-tech]

I'd like to take this issue. I've analyzed the root cause and am confident I can deliver a reliable fix with proper testing

[grantfox-oss]

🦊 GrantFox — @martinshub-tech has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #226)
2. Your PR will be reviewed by the AnchorNet-Org maintainers

Good luck! Track your progress on GrantFox.