mirror of
https://github.com/ComposioHQ/composio.git
synced 2026-09-22 11:46:35 +08:00
Rahul Tarak
18c3b98de6
## Summary - Re-apply the Algolia docs search migration after the previous PR was merged and reverted. - Keep the existing Fumadocs search UI while using Algolia API when search keys are configured, with `/api/search` fallback for local development and tests. - Add a first-party Algolia index builder/sync script that creates section-sized docs records from MDX/OpenAPI/toolkit/changelog content, configures index relevance settings, and replaces index objects without relying on Algolia Crawler. - Add Algolia Insights view/click events and a terminal search relevance test script. - Clean search breadcrumbs so results show labels like `Toolkit` and `Cookbook` instead of duplicated `toolkits > Gmail` formatting. ## Tests - `cd docs && bun run types:check` - `cd docs && bun run sync:search --dry-run` - `cd docs && bunx eslint components/custom-search-dialog.tsx lib/search-index.ts scripts/sync-algolia-search.ts scripts/test-algolia-search.ts` ## Notes - Live Algolia sync requires `ALGOLIA_ADMIN_API_KEY`. - Live search relevance tests require `ALGOLIA_SEARCH_API_KEY` or `NEXT_PUBLIC_ALGOLIA_SEARCH_API_KEY`.
OpenAPI Scripts
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