feat: split API reference into per-product pages for AgentKit and SaaSKit#706
Open
saif-at-scalekit wants to merge 8 commits into
Open
Conversation
- Add Redocly CLI workflow: split monolithic spec into multi-file structure, then selectively bundle per-product specs with --remove-unused-components - Create openapi/agentkit.yaml and openapi/saaskit.yaml as custom root files that into the shared split structure - Add pnpm split-api script chaining split + bundle for both products - Add Scalar API reference pages at /agentkit/apis/ and /saaskit/apis/ - AgentKit page includes quickstart with auth, connected accounts, and tool execution - Update secondary nav: AgentKit links to /agentkit/apis/, SaaSKit to /saaskit/apis/ - Update path fallbacks in secondary-nav-utils for new routes - Existing /apis/ route with full combined spec remains unchanged
… methods
Tag names like 'Connected Accounts' were lowercased but not slugified,
producing 'connected%20accounts' instead of 'connected-accounts'. HTTP
methods were lowercased ('get') but Scalar uses uppercase ('GET').
- java-spring-boot-jwt-timeout: #tag/authentication does not exist, changed to #tag/sessions - check-sso-domain: lowercase get -> GET to match Scalar anchors - create-roles-permissions: lowercase get -> GET - custom-user-attributes: lowercase get -> GET
- Extend openapi-to-markdown integration to generate markdown for all three specs: combined (apis.md), agentkit (agentkit/apis.md), saaskit (saaskit/apis.md) - Write to both dist/ and public/ so files are always served as static assets, fixing intermittent 404s caused by SSR shadowing dist/ files - Add Netlify cache headers for per-product markdown files - Update llms.config.ts with per-product API markdown and OpenAPI spec links - Update generate-llms-index.js with per-product entries in Optional section - Add generated markdown files to .gitignore (build artifacts)
Each product API reference now shows links to switch to the other product's API reference or the combined reference.
Remove .gitignore entries — these must be committed so Netlify's CDN serves them as static assets without hitting SSR.
Instead of generic 'Other API references', each link now describes what the user would be looking for when switching.
Contributor
|
Caution Review failedFailed to post review comments WalkthroughAdds AgentKit OpenAPI spec, many component schemas, and extensive SDK code samples (Go/JavaScript/Java/Python). Updates Netlify headers for API reference pages and .gitignore to ignore dist/. ChangesAgentKit spec, shared schemas, and SDK samples
Site config and ignore updates
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Suggested reviewers
✨ Finishing Touches🧪 Generate unit tests (beta)
|
✅ Deploy Preview for scalekit-starlight ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Splits the monolithic API reference into dedicated per-product pages while preserving the combined view.
Closes SK-399
What changed
Redocly multi-file split
redocly splitto decomposescalekit.scalar.yamlinto a multi-file structure (openapi/paths/,openapi/webhooks/,openapi/components/)openapi/agentkit.yamlandopenapi/saaskit.yamlthat$refonly the relevant paths, webhooks, and tagsredocly bundle --remove-unused-componentsproduces clean per-product specspnpm run split-apicommand chains the full workflowPer-product Astro pages
/agentkit/apis/— AgentKit API reference (Connected Accounts, tool execution)/saaskit/apis/— SaaSKit API reference (SSO, SCIM, directories, sessions, roles, users, etc.)/apis/— Combined reference (unchanged)AgentKit quickstart
agentkit.yamlinfo.description with auth steps, tool execution example, and SDK install for Node.js, Python, JavaNavigation updates
/agentkit/apis//saaskit/apis/Cross-links
Per-product LLM markdown
public/apis.md— combined (777KB)public/agentkit/apis.md— AgentKit only (74.5KB)public/saaskit/apis.md— SaaSKit only (705KB)llms.config.tsandgenerate-llms-index.jswith per-product referencesBug fixes
#tag/anchor links across docsapis.mdintermittent 404 by writing topublic/(static asset) instead of onlydist/Routes
/apis/scalekit.scalar.yaml/agentkit/apis/agentkit.scalar.yaml/saaskit/apis/saaskit.scalar.yamlSummary by CodeRabbit
New Features
Documentation
Chores