fix: migrate api references to single page per-resource approach #1296
Conversation
Add new functions to lib/openApiSpec.ts for loading data for individual API reference pages: - getMethodPageData(): Load data for a single method page - getSchemaPageData(): Load data for a single schema page - getResourceOverviewData(): Load data for resource overview pages - getAllApiReferencePaths(): Generate all static paths for API reference - getSidebarData(): Load sidebar structure for navigation - getResourceOrder(): Get ordered list of resource names - buildSchemaReferences(): Build map of schema names to URL paths - resolveEndpoint(): Parse method config into HTTP method and endpoint Also adds TypeScript types for: - MethodPageData, SchemaPageData, ResourceOverviewData - MethodSummary, SchemaSummary, SubresourceSummary - SidebarPage, SidebarSection, SidebarData - ApiReferencePath, SpecName This is Phase 1 of the API reference migration plan. Co-authored-by: chris <chris@knock.app>
|
Cursor Agent can help with this pull request. Just |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Add new components for multi-page API reference: - ApiReferenceLayout: Shared layout with sidebar navigation - MethodPage: Individual method page component - SchemaPage: Individual schema page component - ResourceOverviewPage: Resource overview with endpoint list - EndpointList: List of endpoints with HTTP method badges Add new page routes: - pages/api-reference/[resource]/index.tsx: Resource overview pages - pages/api-reference/[resource]/[...slug].tsx: Method and schema pages Features: - ISR with 1 hour revalidation - Proper breadcrumb navigation - Schema cross-linking support - Subresource handling Co-authored-by: chris <chris@knock.app>
- Run Prettier to fix code formatting issues - Fix TypeScript type error by casting MDX_COMPONENTS to any - Update next.config.js redirects for backward compatibility - Update api-reference index page to use new multi-page layout Co-authored-by: chris <chris@knock.app>
- Fix JSON serialization issues by using null instead of undefined - Add LightweightApiReferenceProvider for multi-page components - Add useSchemaReferences hook for context-agnostic schema reference access - Update SchemaProperty to use the new hook - Update type definitions for JSON serialization compatibility - Wrap MethodPage and SchemaPage components with providers Build now completes successfully with all static pages generated. Co-authored-by: chris <chris@knock.app>
- Cache OpenAPI spec, Stainless spec, sidebar data, and schema references at module level - Use promise deduplication to handle concurrent requests for the same spec - Avoids re-reading and re-parsing YAML specs for each page during build - Reduces individual page build time from 60+ seconds to under 5 seconds Co-authored-by: chris <chris@knock.app>
Co-authored-by: chris <chris@knock.app>
- Each resource (users, objects, etc.) now has one page with all methods, schemas, and subresources - Deep links like /api-reference/users/get serve the /api-reference/users page - Client-side scrolling handles navigation to specific sections - Deleted per-endpoint [...slug].tsx page - Added getFullResourcePageData function to load complete resource data - Added ResourceFullPage component that wraps ApiReferenceSection with context - Updated next.config.js rewrites for deep link support Co-authored-by: chris <chris@knock.app>
- Extended SidebarContext with currentResourcePath to track which resource page we're on - Updated NavItem to use same-page routing only for links within the current resource - Links to other resources now use standard navigation - This fixes the 'resourceName undefined' error when clicking sidebar links Co-authored-by: chris <chris@knock.app>
1. Fix same-page routing logic to be more precise: - Only use scroll-to-element for links that exactly match or are sub-paths - Prevents /api-reference from matching /api-reference/overview/... links 2. Add guard for undefined resourceData during client-side transitions - Prevents 'Cannot read properties of undefined' error Co-authored-by: chris <chris@knock.app>
Co-authored-by: chris <chris@knock.app>
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 4 potential issues.
Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.
| }; | ||
|
|
||
| export const ContentColumn = ({ children }) => ( | ||
| <Stack pr="3" w="full"> |
There was a problem hiding this comment.
Sticky positioning broken without top value
Medium Severity
The ExampleColumn component has position="sticky" but the style={{ top: "100px" }} was removed. CSS position: sticky requires a top (or bottom/left/right) value to function—without it, the element scrolls normally instead of sticking. This breaks the intended UX where API code examples stay visible while users scroll through documentation.
| const baseUrl = | ||
| stainlessSpec.environments[ | ||
| specName === "api" ? "production" : "production" | ||
| ] || ""; |
There was a problem hiding this comment.
Redundant ternary always returns same value
Low Severity
The expression specName === "api" ? "production" : "production" always evaluates to "production" regardless of whether specName is "api" or "mapi". This appears to be either a copy-paste error or incomplete implementation that could mislead developers about the intended behavior.
| <Component {...pageProps} /> | ||
| <ErrorBoundary> | ||
| <Component {...pageProps} /> | ||
| </ErrorBoundary> |
There was a problem hiding this comment.
ErrorBoundary doesn't reset on route navigation
Medium Severity
The ErrorBoundary wrapping Component lacks a key prop tied to the route. In Next.js pages router, _app.tsx persists across client-side navigations, so once the ErrorBoundary catches an error and sets hasError: true, that state persists when navigating to other pages. Users become stuck seeing the error UI on all subsequent pages until they perform a hard refresh. Adding key={router.asPath} would force React to remount the boundary on navigation, resetting the error state.
cjbell
changed the title
Description
This PR implements Phase 1 of the API reference migration plan, focusing on creating data loading utilities in
lib/openApiSpec.ts.It introduces new TypeScript types and functions to:
These utilities lay the foundation for the new multi-page API reference architecture, allowing for dynamic generation of content from the OpenAPI and Stainless specs.
Todos
Tasks
.cursor/api-reference-migration-plan.md.Screenshots