inkreachhub/inkreach-teable-cli
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(skill): swagger is a curated registry — audit-verified gaps both ways

Browse Source 
Cross-diff of all @Controller routes vs docs-json (486 vs 438 after shape
normalization): real undocumented routes include the entire authority-matrix
family (live 200, 0 doc entries), select-visibility, plugin runtime/proxy,
ShareDB socket internals, oauth-server, health; ~27 doc entries belong to
the enterprise backend and 404 on this CE instance. Completeness check =
controller grep, docs-json alone is not exhaustive.
This commit is contained in:
yeuimu
2026-09-23 05:43:13 +00:00
parent 20c1e48193
commit 8499de27e6
1 changed files with 28 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/inkreach-teable/api-reference/rest-api.md
+28 -1
View File
@@ -177,6 +177,32 @@ curl -s "$BASE/docs-json" | python3 -c "import json,sys; [print(m.upper(), p) fo
ssh -L 3003:localhost:3003 <backend-host> # then use http://localhost:3003/docs-json ssh -L 3003:localhost:3003 <backend-host> # then use http://localhost:3003/docs-json
``` ```
### ⚠️ Swagger is a curated registry, NOT an auto-scan (audited 2026-09-23)
The doc is generated from an explicit `registerRoutes()` registry
(`packages/openapi/src/generate.schema.ts`), so any controller never
registered there is **invisible in /docs**. Cross-diffing every
`@Controller` route in the backend source against docs-json found gaps in
BOTH directions:
- **Real routes missing from swagger** (controller-verified, several
live-200): the whole **authority-matrix** family
(`/api/base/{bid}/authority-matrix*` — the 4-layer permission system, see
`docs/authority-matrix.md` in the app repo); **select-visibility**
(`GET /api/table/{tid}/select-visibility/{rid}/{fid}`); plugin runtime
(`/api/plugin/{pid}/runtime*`, `upload-bundle`, `bridge`, `plugin-proxy/*`,
`csp-origins`); ShareDB internals (`…/socket/doc-ids`,
`…/socket/snapshot-bulk`); oauth-server (`/api/oauth/authorize`,
`/decision`, `/access_token`); import status; admin ops
(performance-cache, heap-snapshot); `/health` + `/health/memory`
(backend origin only — the domain 404s them).
- **Doc entries with no controller on this CE instance** (~27: `/user-integrations*`,
`/unsubscribe/*`, `/billing/*`, `/admin/enterprise-license/*`…): registered
by the shared openapi package but served by the enterprise backend —
they 404 here.
So the completeness check is the **controller grep**, not docs-json.
Route groups NOT detailed in this guide (see docs-json for shapes): Route groups NOT detailed in this guide (see docs-json for shapes):
`/api/auth/*` (session signin/signout, password/email flows, oauth), `/api/auth/*` (session signin/signout, password/email flows, oauth),
`/api/user/*` (profile, lang, timezone, avatar), `/api/space/*` + `/api/user/*` (profile, lang, timezone, avatar), `/api/space/*` +
@@ -193,7 +219,8 @@ automation webhook route), plugin UI endpoints (`/api/plugin/*` panels,
chart, proxy), `/api/v2/integrity`, `/api/v1/ai-proxy`. chart, proxy), `/api/v2/integrity`, `/api/v1/ai-proxy`.
When you use one of these, verify the exact param shape before calling — When you use one of these, verify the exact param shape before calling —
from docs-json (backend origin / ssh tunnel), or from the backend source: from docs-json (backend origin / domain / ssh tunnel), or from the backend
source:
`grep -rh "@Controller(\|@Get(\|@Post(\|@Patch(\|@Put(\|@Delete(" apps/nestjs-backend/src/features --include='*.controller.ts'` `grep -rh "@Controller(\|@Get(\|@Post(\|@Patch(\|@Put(\|@Delete(" apps/nestjs-backend/src/features --include='*.controller.ts'`
in the inkreach-teable app repo. Do not guess key names (the automation in the inkreach-teable app repo. Do not guess key names (the automation
contract lesson applies instance-wide). contract lesson applies instance-wide).