Lingala
b9a790ef4e
## Summary Deprecated REST endpoints now surface the existing `Legacy` badge in generated API-reference indexes, with endpoint-specific tooltip copy instead of the Sessions-specific default. The generator behavior is covered end to end for both v3 and v3.1, including rendered table output. This branch also restores CI compatibility with the organization Actions policy: workflow tool versions still come from `mise.toml`, but installation uses the approved, SHA-pinned setup actions. Secret scanning pins the repaired organization reusable workflow from ComposioHQ/.github#13. ## Changes - Read the OpenAPI `deprecated` flag and emit `legacy: true` only for deprecated operations. - Render `LegacyBadge` on affected endpoint rows with accurate lifecycle tooltip copy. - Regenerate the affected `files` and `connected-accounts` indexes for v3 and v3.1. - Cover the real generator output, active-operation omission, badge count, and tooltip through a focused regression test. - Replace disallowed transitive Actions dependencies while retaining `mise.toml` as the single tool-version source. Endpoint detail pages continue to use `fumadocs-openapi`'s built-in deprecated marker. The indexed endpoints are `GET /files/list` and `POST /connected_accounts/{nanoid}/refresh`; internal operations remain filtered from the docs. ## Spec data The committed OpenAPI snapshots lagged the live backend for `POST /connected_accounts/{nanoid}/refresh`. Both snapshots now carry its current summary, description, and `deprecated: true`; the next `fetch-openapi.mjs` run will preserve that state from the live spec. ## Validation - `bun run test`: 25 passed, 0 failed. - `bun run types:check`: passed. - Focused ESLint and generated-index drift checks: clean. - Composite-action and workflow YAML parsed successfully; extracted tool pins match `mise.toml`. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: jkomyno <alberto@composio.dev>
OpenAPI Scripts
fetch-with-retry.ts
Shared fetchWithRetry helper used by the data-generation scripts
(generate-toolkits.ts, generate-meta-tools.ts). It wraps the global fetch
with rate-limit-aware retry/backoff: it retries 429 and transient 5xx
responses, honors the Retry-After header when present, otherwise falls back to
exponential backoff with jitter, and caps attempts so CI still fails fast when
the backend is genuinely down.
This matters because generate-toolkits.ts issues ~6500 requests per run
(a few catalog pages + 3 per toolkit across a ~2.1k catalog), which can exceed
the backend request limit.
Before this helper, runs failed with 429, and generate-meta-tools.ts — which
runs immediately after — inherited the exhausted rate-limit window.
Toolkit versions
generate-toolkits.ts owns the complete toolkit catalog and always sources it
from the production API. For a version-only repair, run the narrower generator:
COMPOSIO_API_KEY=... bun run generate:toolkit-versions
Both paths share toolkit-versions.ts, so they fetch and apply changelog values
with identical semantics: a toolkit missing from the production changelog gets
version: null. Any COMPOSIO_API_BASE override must normalize to
https://backend.composio.dev/api/v3; non-production sources fail before a
request is made.
fetch-openapi.mjs
Fetches the Composio OpenAPI spec and filters it for use in Fumadocs API reference documentation.
Usage
bun run scripts/fetch-openapi.mjs
This outputs public/openapi.json which is used by lib/openapi.ts.
Why Filtering is Needed
The raw OpenAPI spec from https://backend.composio.dev/api/v3/openapi.json has issues that break documentation generators:
- Endpoints with multiple tags - Causes duplicate entries in sidebar
- Internal endpoints exposed - CLI, Admin, Profiling endpoints shouldn't be in public docs
See OPENAPI_IMPROVEMENTS.md in the fumadocs root for planned fixes to the spec itself.
What Gets Filtered
Ignored Paths
These endpoints are completely removed:
/api/v3/mcp/validate/{uuid}/api/v3/cli/get-session/api/v3/cli/create-session/api/v3/auth/session/logout
Ignored Tags
Endpoints with only these tags are removed:
CLIAdminProfiling
Duplicate Prevention
If an endpoint has multiple tags, only the first tag is kept. This prevents the same endpoint appearing in multiple sidebar sections.
Configuration
The script uses environment variables:
| Variable | Default | Description |
|---|---|---|
OPENAPI_SPEC_URL |
https://backend.composio.dev/api/v3/openapi.json |
Source OpenAPI spec URL |
For staging deployments, set:
OPENAPI_SPEC_URL=https://staging.composio.dev/api/v3/openapi.json