Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,24 @@ initial server render so selector changes can update the matrix without transfer
raw benchmark history or triggering a React Server Component (RSC) round trip. It is a page-owned
backend-for-frontend (BFF), not a reusable public data API.

### API Documentation Synchronization

The public API reference at `/api` and `/zh/api`, plus the OpenAPI 3.1 document at
`/api/openapi.json`, are generated from `packages/app/src/lib/api-documentation.ts`.

**Any change to an API route, request parameter, response shape, status code, authentication,
caching behavior, or shared API type MUST update the documentation registry in the same change.**
Keep `packages/app/src/lib/api-route-catalog.ts` synchronized with every handler under
`packages/app/src/app/api/`; the catalog classifies unpublished routes and records review digests
for handlers and shared contract sources. Do not update a digest without first confirming whether
the human reference, Chinese copy, examples, or OpenAPI schema also need changes.

Run the synchronization guard from `packages/app`:

```bash
bun --env-file=../../.env vitest run src/lib/api-route-catalog.test.ts
```

Static content routes (no DB):

- `/blog` — blog listing (statically generated from MDX files in `content/blog/`)
Expand Down
81 changes: 81 additions & 0 deletions packages/app/cypress/e2e/api-documentation.cy.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
const SITE_URL = 'https://inferencex.semianalysis.com';

describe('API documentation', () => {
it('exposes the localized reference and its OpenAPI contract', () => {
cy.visit('/api');

cy.get('[data-testid="api-reference"]')
.should('contain.text', 'InferenceX API reference')
.and('contain.text', 'Quickstart')
.and('contain.text', 'curl')
.and('contain.text', '/api/v1/availability')
.and('contain.text', 'Endpoint reference');
cy.get('[data-testid="api-openapi-link"]').should('have.attr', 'href', '/api/openapi.json');
cy.get('[data-testid="api-spec-version"]').should('have.text', 'v1 · OpenAPI 3.1');
cy.get('[data-testid="api-endpoint-list-benchmarks"]')
.should('contain.text', 'GET')
.and('contain.text', '/api/v1/benchmarks');
cy.get('[data-testid="api-endpoint-get-collectivex-run"]')
.should('contain.text', 'GET')
.and('contain.text', '/api/v1/collectivex/runs/{runId}');

cy.get('link[rel="alternate"][hreflang="en"]').should('have.attr', 'href', `${SITE_URL}/api`);
cy.get('link[rel="alternate"][hreflang="zh-CN"]').should(
'have.attr',
'href',
`${SITE_URL}/zh/api`,
);
cy.get('link[rel="alternate"][hreflang="x-default"]').should(
'have.attr',
'href',
`${SITE_URL}/api`,
);
cy.get('[data-testid="language-toggle"]')
.should('have.attr', 'href', '/zh/api')
.and('have.attr', 'hreflang', 'zh-CN');
cy.get('[data-testid="footer-link-api"]')
.should('have.attr', 'href', '/api')
.and('have.text', 'API Reference');

cy.request('/api/openapi.json').then(({ body, headers, status }) => {
expect(status).to.equal(200);
expect(headers['content-type']).to.contain('application/json');
expect(body).to.have.property('openapi', '3.1.0');
expect(body.paths['/api/v1/benchmarks'].get).to.have.property(
'operationId',
'list-benchmarks',
);
expect(body.paths['/api/v1/collectivex/runs/{runId}'].get).to.have.property(
'operationId',
'get-collectivex-run',
);
});

cy.visit('/zh/api');

cy.get('[data-testid="api-reference"]')
.should('contain.text', 'InferenceX API 参考文档')
.and('contain.text', '快速入门')
.and('contain.text', '约定')
.and('contain.text', '端点参考')
.and('contain.text', 'BenchmarkRow 与指标');
cy.get('[data-testid="api-openapi-link"]').should('have.attr', 'href', '/api/openapi.json');
cy.get('link[rel="alternate"][hreflang="en"]').should('have.attr', 'href', `${SITE_URL}/api`);
cy.get('link[rel="alternate"][hreflang="zh-CN"]').should(
'have.attr',
'href',
`${SITE_URL}/zh/api`,
);
cy.get('link[rel="alternate"][hreflang="x-default"]').should(
'have.attr',
'href',
`${SITE_URL}/api`,
);
cy.get('[data-testid="language-toggle"]')
.should('have.attr', 'href', '/api')
.and('have.attr', 'hreflang', 'en');
cy.get('[data-testid="footer-link-api"]')
.should('have.attr', 'href', '/zh/api')
.and('have.text', 'API 参考文档');
});
});
13 changes: 13 additions & 0 deletions packages/app/src/app/api/openapi.json/route.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
import { NextResponse } from 'next/server';

import { buildOpenApiDocument } from '@/lib/api-documentation';

export const dynamic = 'force-static';

export function GET() {
return NextResponse.json(buildOpenApiDocument(), {
headers: {
'Cache-Control': 'public, max-age=0, s-maxage=3600, stale-while-revalidate=86400',
},
});
}
30 changes: 30 additions & 0 deletions packages/app/src/app/api/page.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
import type { Metadata } from 'next';

import { ApiReferencePage } from '@/components/api-documentation/api-reference-page';
import { getApiDocumentation } from '@/lib/api-documentation';
import { enAlternates } from '@/lib/i18n';
import { SITE_NAME, SITE_URL } from '@semianalysisai/inferencex-constants';

const documentation = getApiDocumentation('en');

export const metadata: Metadata = {
title: documentation.title,
description: documentation.description,
alternates: enAlternates('/api'),
openGraph: {
title: `${documentation.title} | ${SITE_NAME}`,
description: documentation.description,
url: `${SITE_URL}/api`,
locale: 'en_US',
type: 'article',
},
twitter: {
card: 'summary_large_image',
title: `${documentation.title} | ${SITE_NAME}`,
description: documentation.description,
},
};

export default function ApiPage() {
return <ApiReferencePage locale="en" />;
}
2 changes: 2 additions & 0 deletions packages/app/src/app/llms.txt/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ export async function GET() {
'',
`- [Dashboard](${SITE_URL})`,
`- [Articles](${SITE_URL}/blog)`,
`- [API Reference](${SITE_URL}/api)`,
`- [OpenAPI 3.1 Specification](${SITE_URL}/api/openapi.json)`,
`- [RSS Feed](${SITE_URL}/feed.xml)`,
`- [Full content for LLMs](${SITE_URL}/llms-full.txt)`,
`- [GitHub](https://github.com/SemiAnalysisAI/InferenceX)`,
Expand Down
1 change: 1 addition & 0 deletions packages/app/src/app/sitemap.ts
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,7 @@ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
priority: 0.8,
}),
...localizedPair('/datasets', { lastModified: now, changeFrequency: 'weekly', priority: 0.6 }),
...localizedPair('/api', { lastModified: now, changeFrequency: 'monthly', priority: 0.7 }),
...localizedPair('/blog', { lastModified: now, changeFrequency: 'weekly', priority: 0.8 }),
...localizedPair('/glossary', {
lastModified: now,
Expand Down
30 changes: 30 additions & 0 deletions packages/app/src/app/zh/api/page.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
import type { Metadata } from 'next';

import { ApiReferencePage } from '@/components/api-documentation/api-reference-page';
import { getApiDocumentation } from '@/lib/api-documentation';
import { zhAlternates, ZH_OG_LOCALE } from '@/lib/i18n';
import { SITE_NAME, SITE_URL } from '@semianalysisai/inferencex-constants';

const documentation = getApiDocumentation('zh');

export const metadata: Metadata = {
title: documentation.title,
description: documentation.description,
alternates: zhAlternates('/api'),
openGraph: {
title: `${documentation.title} | ${SITE_NAME}`,
description: documentation.description,
url: `${SITE_URL}/zh/api`,
locale: ZH_OG_LOCALE,
type: 'article',
},
twitter: {
card: 'summary_large_image',
title: `${documentation.title} | ${SITE_NAME}`,
description: documentation.description,
},
};

export default function ApiPageZh() {
return <ApiReferencePage locale="zh" />;
}
Loading