Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

fix(docs): show Legacy badge on deprecated API detail pages

jkomynoed95bf822ca1
diff --git a/docs/app/(home)/reference/(v31)/[[...slug]]/page.tsx b/docs/app/(home)/reference/(v31)/[[...slug]]/page.tsx
index d6713e4e3..6dba8bbbe 100644
--- a/docs/app/(home)/reference/(v31)/[[...slug]]/page.tsx
+++ b/docs/app/(home)/reference/(v31)/[[...slug]]/page.tsx
@@ -12,9 +12,12 @@ import { createRelativeLink } from 'fumadocs-ui/mdx';
import type { ApiPageProps } from 'fumadocs-openapi/ui';
import { PageActions } from '@/components/page-actions';
import { EditOnGitHub } from '@/components/edit-on-github';
-import { VersionBadge, extractVersionFromPath } from '@/components/version-badge';
+import { extractVersionFromPath } from '@/components/version-badge';
+import { ApiPageTitle } from '@/components/api-page-title';
+import { isApiPageDeprecated } from '@/lib/api-deprecation';
+import type { OpenApiSchemaPageData } from '@/lib/api-deprecation';
-interface OpenAPIPageData {
+interface OpenAPIPageData extends OpenApiSchemaPageData {
title: string;
description?: string;
getAPIPageProps: () => ApiPageProps;
@@ -36,17 +39,15 @@ export default async function Page({
const detectedVersion = apiProps.operations?.[0]?.path
? extractVersionFromPath(apiProps.operations[0].path)
: null;
+ const deprecated = isApiPageDeprecated(pageData, apiProps.operations);
return (
<DocsPage full footer={{ enabled: false }} tableOfContentPopover={{ enabled: false }}>
<div className="mb-4 flex items-start justify-between gap-4">
- <h1 className="text-2xl font-semibold">
- {pageData.title}
- {detectedVersion && (
- <span className="ml-2 align-middle">
- <VersionBadge version={detectedVersion} />
- </span>
- )}
- </h1>
+ <ApiPageTitle
+ title={pageData.title}
+ version={detectedVersion}
+ deprecated={deprecated}
+ />
<PageActions path={page.url} variant="inline" />
</div>
<DocsBody>
diff --git a/docs/app/(home)/reference/v3/[[...slug]]/page.tsx b/docs/app/(home)/reference/v3/[[...slug]]/page.tsx
index eb1f08c02..999c17460 100644
--- a/docs/app/(home)/reference/v3/[[...slug]]/page.tsx
+++ b/docs/app/(home)/reference/v3/[[...slug]]/page.tsx
@@ -12,9 +12,12 @@ import { createRelativeLink } from 'fumadocs-ui/mdx';
import type { ApiPageProps } from 'fumadocs-openapi/ui';
import { PageActions } from '@/components/page-actions';
import { EditOnGitHub } from '@/components/edit-on-github';
-import { VersionBadge, extractVersionFromPath } from '@/components/version-badge';
+import { extractVersionFromPath } from '@/components/version-badge';
+import { ApiPageTitle } from '@/components/api-page-title';
+import { isApiPageDeprecated } from '@/lib/api-deprecation';
+import type { OpenApiSchemaPageData } from '@/lib/api-deprecation';
-interface OpenAPIPageData {
+interface OpenAPIPageData extends OpenApiSchemaPageData {
title: string;
description?: string;
getAPIPageProps: () => ApiPageProps;
@@ -44,17 +47,15 @@ export default async function Page({
const detectedVersion = apiProps.operations?.[0]?.path
? extractVersionFromPath(apiProps.operations[0].path)
: null;
+ const deprecated = isApiPageDeprecated(pageData, apiProps.operations);
return (
<DocsPage full footer={{ enabled: false }} tableOfContentPopover={{ enabled: false }}>
<div className="mb-4 flex items-start justify-between gap-4">
- <h1 className="text-2xl font-semibold">
- {pageData.title}
- {detectedVersion && (
- <span className="ml-2 align-middle">
- <VersionBadge version={detectedVersion} />
- </span>
- )}
- </h1>
+ <ApiPageTitle
+ title={pageData.title}
+ version={detectedVersion}
+ deprecated={deprecated}
+ />
<PageActions path={page.url} variant="inline" />
</div>
<DocsBody>
diff --git a/docs/components/api-endpoints-table.tsx b/docs/components/api-endpoints-table.tsx
index c2553babf..a36d5964a 100644
--- a/docs/components/api-endpoints-table.tsx
+++ b/docs/components/api-endpoints-table.tsx
@@ -1,7 +1,7 @@
'use client';
import { useApiVersion } from '@/lib/use-api-version';
-import { LegacyBadge } from '@/components/legacy-badge';
+import { DeprecatedApiLegacyBadge } from '@/components/legacy-badge';
interface Endpoint {
method: string;
@@ -39,9 +39,7 @@ export function ApiEndpointsTable({ endpoints }: { endpoints: Endpoint[] }) {
<a href={ep.href}>{ep.summary}</a>
{ep.legacy && (
<span className="ml-2 inline-flex align-middle">
- <LegacyBadge
- title="Deprecated API endpoint; kept for existing integrations and may be removed in a future release"
- />
+ <DeprecatedApiLegacyBadge />
</span>
)}
</td>
diff --git a/docs/components/api-page-title.tsx b/docs/components/api-page-title.tsx
new file mode 100644
index 000000000..618c7f636
--- /dev/null
+++ b/docs/components/api-page-title.tsx
@@ -0,0 +1,30 @@
+import { DeprecatedApiLegacyBadge } from '@/components/legacy-badge';
+import { VersionBadge } from '@/components/version-badge';
+
+interface ApiPageTitleProps {
+ title: string;
+ version: string | null;
+ deprecated: boolean;
+}
+
+export function ApiPageTitle({
+ title,
+ version,
+ deprecated,
+}: ApiPageTitleProps) {
+ return (
+ <h1 className="text-2xl font-semibold">
+ {title}
+ {version && (
+ <span className="ml-2 align-middle">
+ <VersionBadge version={version} />
+ </span>
+ )}
+ {deprecated && (
+ <span className="ml-2 inline-flex align-middle">
+ <DeprecatedApiLegacyBadge />
+ </span>
+ )}
+ </h1>
+ );
+}
diff --git a/docs/components/legacy-badge.tsx b/docs/components/legacy-badge.tsx
index 40b31c253..3bb4c6bd6 100644
--- a/docs/components/legacy-badge.tsx
+++ b/docs/components/legacy-badge.tsx
@@ -9,6 +9,9 @@ interface LegacyBadgeProps {
title?: string;
}
+export const DEPRECATED_API_LEGACY_TITLE =
+ 'Deprecated API endpoint; kept for existing integrations and may be removed in a future release';
+
export function LegacyBadge({
title = 'Legacy: superseded by sessions; kept for existing integrations',
}: LegacyBadgeProps) {
@@ -21,3 +24,7 @@ export function LegacyBadge({
</span>
);
}
+
+export function DeprecatedApiLegacyBadge() {
+ return <LegacyBadge title={DEPRECATED_API_LEGACY_TITLE} />;
+}
diff --git a/docs/lib/api-deprecation.ts b/docs/lib/api-deprecation.ts
new file mode 100644
index 000000000..dbaa322e0
--- /dev/null
+++ b/docs/lib/api-deprecation.ts
@@ -0,0 +1,32 @@
+interface ApiPageOperation {
+ method: string;
+ path: string;
+}
+
+export interface OpenApiSchemaPageData {
+ getSchema: () => {
+ dereferenced: {
+ paths?: Record<
+ string,
+ Record<string, { deprecated?: boolean } | undefined> | undefined
+ >;
+ };
+ };
+}
+
+/**
+ * Returns whether any operation rendered by an OpenAPI page is deprecated.
+ * Operation detail pages currently contain one operation, but checking all of
+ * them keeps the helper correct for grouped pages too.
+ */
+export function isApiPageDeprecated(
+ pageData: OpenApiSchemaPageData,
+ operations?: ApiPageOperation[],
+): boolean {
+ if (!operations || operations.length === 0) return false;
+
+ const paths = pageData.getSchema().dereferenced.paths;
+ return operations.some(
+ ({ method, path }) => paths?.[path]?.[method]?.deprecated === true,
+ );
+}
diff --git a/docs/tests/integration/rendering.test.ts b/docs/tests/integration/rendering.test.ts
index 8f5f0fc12..d704ab3d0 100644
--- a/docs/tests/integration/rendering.test.ts
+++ b/docs/tests/integration/rendering.test.ts
@@ -19,6 +19,21 @@ const CRITICAL_PAGES = [
{ path: "/reference", name: "Reference index" },
];
+const DEPRECATED_API_LEGACY_TITLE =
+ "Deprecated API endpoint; kept for existing integrations and may be removed in a future release";
+
+const DEPRECATED_API_PAGES = [
+ "/reference/api-reference/connected-accounts/postConnectedAccountsByNanoidRefresh",
+ "/reference/api-reference/files/getFilesList",
+ "/reference/v3/api-reference/connected-accounts/postConnectedAccountsByNanoidRefresh",
+ "/reference/v3/api-reference/files/getFilesList",
+];
+
+const ACTIVE_API_PAGES = [
+ "/reference/api-reference/files/postFilesUploadRequest",
+ "/reference/v3/api-reference/files/postFilesUploadRequest",
+];
+
describe("Page rendering - critical pages", () => {
for (const { path, name } of CRITICAL_PAGES) {
test(`${name} (${path}) returns 200`, async () => {
@@ -56,6 +71,28 @@ describe("Page rendering - content markers", () => {
});
});
+describe("Page rendering - deprecated API endpoints", () => {
+ for (const path of DEPRECATED_API_PAGES) {
+ test(`${path} renders the Legacy badge`, async () => {
+ const res = await fetchPage(path);
+ const html = await res.text();
+
+ expect(res.status).toBe(200);
+ expect(html).toContain(DEPRECATED_API_LEGACY_TITLE);
+ });
+ }
+
+ for (const path of ACTIVE_API_PAGES) {
+ test(`${path} omits the Legacy badge`, async () => {
+ const res = await fetchPage(path);
+ const html = await res.text();
+
+ expect(res.status).toBe(200);
+ expect(html).not.toContain(DEPRECATED_API_LEGACY_TITLE);
+ });
+ }
+});
+
describe("Page rendering - error handling", () => {
test("non-existent page returns 404", async () => {
const res = await fetchPage("/docs/this-page-does-not-exist-ever");
diff --git a/docs/tests/static/api-deprecation.test.tsx b/docs/tests/static/api-deprecation.test.tsx
index e45e35e3d..bcb1c3aa0 100644
--- a/docs/tests/static/api-deprecation.test.tsx
+++ b/docs/tests/static/api-deprecation.test.tsx
@@ -9,6 +9,8 @@ mock.module("next/navigation", () => ({
}));
const { ApiEndpointsTable } = await import("../../components/api-endpoints-table");
+const { ApiPageTitle } = await import("../../components/api-page-title");
+const { isApiPageDeprecated } = await import("../../lib/api-deprecation");
const DOCS_DIR = join(import.meta.dir, "../..");
const GENERATOR_PATH = join(DOCS_DIR, "scripts/generate-api-index.ts");
@@ -115,6 +117,69 @@ afterEach(async () => {
});
describe("deprecated API endpoints", () => {
+ test("renders Legacy on a deprecated API endpoint detail title", () => {
+ const operation = {
+ method: "get",
+ path: "/v3.1/tasks/deprecated",
+ };
+ const pageData = {
+ getSchema: () => ({
+ dereferenced: {
+ paths: {
+ [operation.path]: {
+ [operation.method]: { deprecated: true },
+ },
+ },
+ },
+ }),
+ };
+
+ const deprecated = isApiPageDeprecated(pageData, [operation]);
+ const html = renderToStaticMarkup(
+ <ApiPageTitle
+ title="Deprecated task endpoint"
+ version="3.1"
+ deprecated={deprecated}
+ />,
+ );
+
+ expect(deprecated).toBe(true);
+ expect(html.match(/>Legacy<\/span>/g)).toHaveLength(1);
+ expect(html).toContain(
+ 'title="Deprecated API endpoint; kept for existing integrations and may be removed in a future release"',
+ );
+ });
+
+ test("omits Legacy from an active API endpoint detail title", () => {
+ const operation = {
+ method: "post",
+ path: "/v3.1/tasks/active",
+ };
+ const pageData = {
+ getSchema: () => ({
+ dereferenced: {
+ paths: {
+ [operation.path]: {
+ [operation.method]: {},
+ },
+ },
+ },
+ }),
+ };
+
+ const deprecated = isApiPageDeprecated(pageData, [operation]);
+ const html = renderToStaticMarkup(
+ <ApiPageTitle
+ title="Active task endpoint"
+ version="3.1"
+ deprecated={deprecated}
+ />,
+ );
+
+ expect(deprecated).toBe(false);
+ expect(html).not.toContain(">Legacy</span>");
+ });
+
test("serializes legacy only for deprecated v3.1 and v3 operations", async () => {
const fixtureDir = await generateFixture();
const v31Content = await readFile(