Automatically update API reference for manage-api and API reference for run-api
#1131
Conversation
|
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Claude finished @dimaMachina's task —— View job Code Review AnalysisI'll provide a comprehensive review of this PR which appears to be a significant refactoring of the API documentation generation system. Todo List:
🏗️ Overall AssessmentThis PR represents a well-executed modernization of the documentation infrastructure with significant architectural improvements. The changes demonstrate thoughtful engineering decisions that address scalability, maintainability, and developer experience. ✅ Strengths1. Smart Migration Strategy
2. Improved OpenAPI Architecture // agents-docs/src/lib/openapi.ts:6-8
input: () => ({
index: 'https://agents-manage-api.preview.inkeep.com/openapi.json',
'run-api': 'https://agents-run-api.preview.inkeep.com/openapi.json',
}),
3. Enhanced Build Process // agents-docs/package.json:17-20
"generate-openapi": "node scripts/generate-openapi-docs.ts --experimental-strip-types",
"generate-classnames": "node scripts/generate-classnames.ts --experimental-strip-types",
"prebuild": "pnpm generate-classnames",
"validate-link": "node scripts/validate-link.ts --experimental-strip-types"
4. Dependency Management
|
| @@ -1,27 +0,0 @@ | |||
| # deps | |||
There was a problem hiding this comment.
not needed, .source already specified in root .gitignore
Line 67 in 06fd7f0
| { page: 'api-reference', icon: 'LuDatabaseZap' }, | ||
| { page: 'api-reference/run-api', icon: 'LuPlay' }, |
There was a problem hiding this comment.
added possibility providing icon for individual pages, but IMO we should stays with meta.json convention
See https://inkeep.slack.com/archives/C08QXR5CWBH/p1763979484675009
| // Package ts-morph can't be external | ||
| // The request ts-morph matches serverExternalPackages (or the default list). | ||
| transpilePackages: ['prettier', 'ts-morph'], | ||
| transpilePackages: ['prettier', 'ts-morph', 'shiki'], |
There was a problem hiding this comment.
removes warning while running next build
| }} | ||
| container={{ | ||
| className: 'lg:pt-0! [&>#nd-toc]:!pt-6 [&>#nd-toc]:pb-4 h-full min-h-0', | ||
| style: tocEnabled ? undefined : { '--fd-toc-width': 0 }, |
There was a problem hiding this comment.
| input: () => ({ | ||
| index: 'https://agents-manage-api.preview.inkeep.com/openapi.json', | ||
| 'run-api': 'https://agents-run-api.preview.inkeep.com/openapi.json', | ||
| }), |
There was a problem hiding this comment.
cc @amikofalvy 🚀 I guess I need inject environment variable here? INKEEP_AGENTS_MANAGE_API_URL and INKEEP_AGENTS_RUN_API_URL instead of https://agents-manage-api.preview.inkeep.com and https://agents-run-api.preview.inkeep.com
| "content/docs/talk-to-your-agents/a2a.mdx", | ||
| "content/docs/talk-to-your-agents/mcp-server.mdx", | ||
| ".next/dev/types/**/*.ts", | ||
| "scripts/generate-classnames.mjs" |
There was a problem hiding this comment.
since all scripts were migrated to .ts, no longer need
| docsFiles.forEach((file) => { | ||
| const info = parseFilePath(path.relative('content/docs', file.path)); | ||
| const slugs = getSlugs(info); | ||
| const url = `/${slugs.join('/')}`; | ||
| validUrls[url] = true; | ||
|
|
||
| const hashes = getTableOfContents(file.content).map((item) => item.url.slice(1)); | ||
| hashes.forEach((hash) => { | ||
| if (hash) { | ||
| validUrls[`${url}#${hash}`] = true; | ||
| } | ||
| }); | ||
| }); |
There was a problem hiding this comment.
I am not sure that this is needed..
| './mdx-components.{ts,tsx}', | ||
| './src/mdx-components.{ts,tsx}', |
There was a problem hiding this comment.
wrong path, maybe we should just specify ./src/**/*.{ts,tsx} ?
| darkMode: ['class'], | ||
| const config: Config = { | ||
| darkMode: 'class', |
| "dev": "next --turbo -p 3010", | ||
| "start": "next start", | ||
| "dev": "next --port 3010", | ||
| "start": "next start --port 3010", |
There was a problem hiding this comment.
use 3010 port for next start too
| "license": "SEE LICENSE IN LICENSE.md", | ||
| "scripts": { | ||
| "build": "next build", | ||
| "dev": "next --turbo -p 3010", |
There was a problem hiding this comment.
turbo is by default with Next.js 16
| | Route | Description | | ||
| | ------------------------- | ------------------------------------------------------ | | ||
| | `app/(home)` | The route group for your landing page and other pages. | | ||
| | `app/docs` | The documentation layout and pages. | | ||
| | `app/api/search/route.ts` | The Route Handler for search. | |
There was a problem hiding this comment.
removed, since project structure was changed
| url: page.url, | ||
| title: page.data.title, | ||
| icon: page.data.icon, | ||
| icon: item.icon ?? page.data.icon, |
There was a problem hiding this comment.
| const OUTPUT_DIR = './content/docs/api-reference'; | ||
| const DEFAULT_ICON = 'LuDatabaseZap'; | ||
|
|
||
| async function addIconToFrontmatter(filePath) { |
There was a problem hiding this comment.
i think this is weird solution, I added possibility specifying icons for individual pages in navigation.ts file
auto update API reference for
manage-apiNEW API reference for
run-apiupdates all fumadocs dependencies
refactor all scripts from
jstots, thanks to--experimental-strip-typesflagpolish README
refactor
tailwind.config.mjstotsadd
"type": "module"inpackage.jsonto avoid specifying.mjsextension (likepostcss.config.mjs)pnpm generate-openapiandpnpm validate-linkinprebuildscriptfix a lot of broken urls (should be done in another PR)
