@devries-cameron20 / composio-1 / commits / ed95bf822
Fork 0

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

jkomyno committed Jul 22, 2026 at 21:25 UTC ed95bf822ca11736af7ec883918000e5e5cfab92
8 files changed +195 -24
docs/app/(home)/reference/(v31)/[[...slug]]/page.tsx
+11 -10
@@ -12,9 +12,12 @@ import { createRelativeLink } from 'fumadocs-ui/mdx';
12 import type { ApiPageProps } from 'fumadocs-openapi/ui';
13 import { PageActions } from '@/components/page-actions';
14 import { EditOnGitHub } from '@/components/edit-on-github';
15 -import { VersionBadge, extractVersionFromPath } from '@/components/version-badge';
15 +import { extractVersionFromPath } from '@/components/version-badge';
16 +import { ApiPageTitle } from '@/components/api-page-title';
17 +import { isApiPageDeprecated } from '@/lib/api-deprecation';
18 +import type { OpenApiSchemaPageData } from '@/lib/api-deprecation';
19
17 -interface OpenAPIPageData {
20 +interface OpenAPIPageData extends OpenApiSchemaPageData {
21 title: string;
22 description?: string;
23 getAPIPageProps: () => ApiPageProps;
@@ -36,17 +39,15 @@ export default async function Page({
39 const detectedVersion = apiProps.operations?.[0]?.path
40 ? extractVersionFromPath(apiProps.operations[0].path)
41 : null;
42 + const deprecated = isApiPageDeprecated(pageData, apiProps.operations);
43 return (
44 <DocsPage full footer={{ enabled: false }} tableOfContentPopover={{ enabled: false }}>
45 <div className="mb-4 flex items-start justify-between gap-4">
42 - <h1 className="text-2xl font-semibold">
43 - {pageData.title}
44 - {detectedVersion && (
45 - <span className="ml-2 align-middle">
46 - <VersionBadge version={detectedVersion} />
47 - </span>
48 - )}
49 - </h1>
46 + <ApiPageTitle
47 + title={pageData.title}
48 + version={detectedVersion}
49 + deprecated={deprecated}
50 + />
51 <PageActions path={page.url} variant="inline" />
52 </div>
53 <DocsBody>
docs/app/(home)/reference/v3/[[...slug]]/page.tsx
+11 -10
@@ -12,9 +12,12 @@ import { createRelativeLink } from 'fumadocs-ui/mdx';
12 import type { ApiPageProps } from 'fumadocs-openapi/ui';
13 import { PageActions } from '@/components/page-actions';
14 import { EditOnGitHub } from '@/components/edit-on-github';
15 -import { VersionBadge, extractVersionFromPath } from '@/components/version-badge';
15 +import { extractVersionFromPath } from '@/components/version-badge';
16 +import { ApiPageTitle } from '@/components/api-page-title';
17 +import { isApiPageDeprecated } from '@/lib/api-deprecation';
18 +import type { OpenApiSchemaPageData } from '@/lib/api-deprecation';
19
17 -interface OpenAPIPageData {
20 +interface OpenAPIPageData extends OpenApiSchemaPageData {
21 title: string;
22 description?: string;
23 getAPIPageProps: () => ApiPageProps;
@@ -44,17 +47,15 @@ export default async function Page({
47 const detectedVersion = apiProps.operations?.[0]?.path
48 ? extractVersionFromPath(apiProps.operations[0].path)
49 : null;
50 + const deprecated = isApiPageDeprecated(pageData, apiProps.operations);
51 return (
52 <DocsPage full footer={{ enabled: false }} tableOfContentPopover={{ enabled: false }}>
53 <div className="mb-4 flex items-start justify-between gap-4">
50 - <h1 className="text-2xl font-semibold">
51 - {pageData.title}
52 - {detectedVersion && (
53 - <span className="ml-2 align-middle">
54 - <VersionBadge version={detectedVersion} />
55 - </span>
56 - )}
57 - </h1>
54 + <ApiPageTitle
55 + title={pageData.title}
56 + version={detectedVersion}
57 + deprecated={deprecated}
58 + />
59 <PageActions path={page.url} variant="inline" />
60 </div>
61 <DocsBody>
docs/components/api-endpoints-table.tsx
+2 -4
@@ -1,7 +1,7 @@
1 'use client';
2
3 import { useApiVersion } from '@/lib/use-api-version';
4 -import { LegacyBadge } from '@/components/legacy-badge';
4 +import { DeprecatedApiLegacyBadge } from '@/components/legacy-badge';
5
6 interface Endpoint {
7 method: string;
@@ -39,9 +39,7 @@ export function ApiEndpointsTable({ endpoints }: { endpoints: Endpoint[] }) {
39 <a href={ep.href}>{ep.summary}</a>
40 {ep.legacy && (
41 <span className="ml-2 inline-flex align-middle">
42 - <LegacyBadge
43 - title="Deprecated API endpoint; kept for existing integrations and may be removed in a future release"
44 - />
42 + <DeprecatedApiLegacyBadge />
43 </span>
44 )}
45 </td>
docs/components/api-page-title.tsx new
+30
@@ -0,0 +1,30 @@
1 +import { DeprecatedApiLegacyBadge } from '@/components/legacy-badge';
2 +import { VersionBadge } from '@/components/version-badge';
3 +
4 +interface ApiPageTitleProps {
5 + title: string;
6 + version: string | null;
7 + deprecated: boolean;
8 +}
9 +
10 +export function ApiPageTitle({
11 + title,
12 + version,
13 + deprecated,
14 +}: ApiPageTitleProps) {
15 + return (
16 + <h1 className="text-2xl font-semibold">
17 + {title}
18 + {version && (
19 + <span className="ml-2 align-middle">
20 + <VersionBadge version={version} />
21 + </span>
22 + )}
23 + {deprecated && (
24 + <span className="ml-2 inline-flex align-middle">
25 + <DeprecatedApiLegacyBadge />
26 + </span>
27 + )}
28 + </h1>
29 + );
30 +}
docs/components/legacy-badge.tsx
+7
@@ -9,6 +9,9 @@ interface LegacyBadgeProps {
9 title?: string;
10 }
11
12 +export const DEPRECATED_API_LEGACY_TITLE =
13 + 'Deprecated API endpoint; kept for existing integrations and may be removed in a future release';
14 +
15 export function LegacyBadge({
16 title = 'Legacy: superseded by sessions; kept for existing integrations',
17 }: LegacyBadgeProps) {
@@ -21,3 +24,7 @@ export function LegacyBadge({
24 </span>
25 );
26 }
27 +
28 +export function DeprecatedApiLegacyBadge() {
29 + return <LegacyBadge title={DEPRECATED_API_LEGACY_TITLE} />;
30 +}
docs/lib/api-deprecation.ts new
+32
@@ -0,0 +1,32 @@
1 +interface ApiPageOperation {
2 + method: string;
3 + path: string;
4 +}
5 +
6 +export interface OpenApiSchemaPageData {
7 + getSchema: () => {
8 + dereferenced: {
9 + paths?: Record<
10 + string,
11 + Record<string, { deprecated?: boolean } | undefined> | undefined
12 + >;
13 + };
14 + };
15 +}
16 +
17 +/**
18 + * Returns whether any operation rendered by an OpenAPI page is deprecated.
19 + * Operation detail pages currently contain one operation, but checking all of
20 + * them keeps the helper correct for grouped pages too.
21 + */
22 +export function isApiPageDeprecated(
23 + pageData: OpenApiSchemaPageData,
24 + operations?: ApiPageOperation[],
25 +): boolean {
26 + if (!operations || operations.length === 0) return false;
27 +
28 + const paths = pageData.getSchema().dereferenced.paths;
29 + return operations.some(
30 + ({ method, path }) => paths?.[path]?.[method]?.deprecated === true,
31 + );
32 +}
docs/tests/integration/rendering.test.ts
+37
@@ -19,6 +19,21 @@ const CRITICAL_PAGES = [
19 { path: "/reference", name: "Reference index" },
20 ];
21
22 +const DEPRECATED_API_LEGACY_TITLE =
23 + "Deprecated API endpoint; kept for existing integrations and may be removed in a future release";
24 +
25 +const DEPRECATED_API_PAGES = [
26 + "/reference/api-reference/connected-accounts/postConnectedAccountsByNanoidRefresh",
27 + "/reference/api-reference/files/getFilesList",
28 + "/reference/v3/api-reference/connected-accounts/postConnectedAccountsByNanoidRefresh",
29 + "/reference/v3/api-reference/files/getFilesList",
30 +];
31 +
32 +const ACTIVE_API_PAGES = [
33 + "/reference/api-reference/files/postFilesUploadRequest",
34 + "/reference/v3/api-reference/files/postFilesUploadRequest",
35 +];
36 +
37 describe("Page rendering - critical pages", () => {
38 for (const { path, name } of CRITICAL_PAGES) {
39 test(`${name} (${path}) returns 200`, async () => {
@@ -56,6 +71,28 @@ describe("Page rendering - content markers", () => {
71 });
72 });
73
74 +describe("Page rendering - deprecated API endpoints", () => {
75 + for (const path of DEPRECATED_API_PAGES) {
76 + test(`${path} renders the Legacy badge`, async () => {
77 + const res = await fetchPage(path);
78 + const html = await res.text();
79 +
80 + expect(res.status).toBe(200);
81 + expect(html).toContain(DEPRECATED_API_LEGACY_TITLE);
82 + });
83 + }
84 +
85 + for (const path of ACTIVE_API_PAGES) {
86 + test(`${path} omits the Legacy badge`, async () => {
87 + const res = await fetchPage(path);
88 + const html = await res.text();
89 +
90 + expect(res.status).toBe(200);
91 + expect(html).not.toContain(DEPRECATED_API_LEGACY_TITLE);
92 + });
93 + }
94 +});
95 +
96 describe("Page rendering - error handling", () => {
97 test("non-existent page returns 404", async () => {
98 const res = await fetchPage("/docs/this-page-does-not-exist-ever");
docs/tests/static/api-deprecation.test.tsx
+65
@@ -9,6 +9,8 @@ mock.module("next/navigation", () => ({
9 }));
10
11 const { ApiEndpointsTable } = await import("../../components/api-endpoints-table");
12 +const { ApiPageTitle } = await import("../../components/api-page-title");
13 +const { isApiPageDeprecated } = await import("../../lib/api-deprecation");
14
15 const DOCS_DIR = join(import.meta.dir, "../..");
16 const GENERATOR_PATH = join(DOCS_DIR, "scripts/generate-api-index.ts");
@@ -115,6 +117,69 @@ afterEach(async () => {
117 });
118
119 describe("deprecated API endpoints", () => {
120 + test("renders Legacy on a deprecated API endpoint detail title", () => {
121 + const operation = {
122 + method: "get",
123 + path: "/v3.1/tasks/deprecated",
124 + };
125 + const pageData = {
126 + getSchema: () => ({
127 + dereferenced: {
128 + paths: {
129 + [operation.path]: {
130 + [operation.method]: { deprecated: true },
131 + },
132 + },
133 + },
134 + }),
135 + };
136 +
137 + const deprecated = isApiPageDeprecated(pageData, [operation]);
138 + const html = renderToStaticMarkup(
139 + <ApiPageTitle
140 + title="Deprecated task endpoint"
141 + version="3.1"
142 + deprecated={deprecated}
143 + />,
144 + );
145 +
146 + expect(deprecated).toBe(true);
147 + expect(html.match(/>Legacy<\/span>/g)).toHaveLength(1);
148 + expect(html).toContain(
149 + 'title="Deprecated API endpoint; kept for existing integrations and may be removed in a future release"',
150 + );
151 + });
152 +
153 + test("omits Legacy from an active API endpoint detail title", () => {
154 + const operation = {
155 + method: "post",
156 + path: "/v3.1/tasks/active",
157 + };
158 + const pageData = {
159 + getSchema: () => ({
160 + dereferenced: {
161 + paths: {
162 + [operation.path]: {
163 + [operation.method]: {},
164 + },
165 + },
166 + },
167 + }),
168 + };
169 +
170 + const deprecated = isApiPageDeprecated(pageData, [operation]);
171 + const html = renderToStaticMarkup(
172 + <ApiPageTitle
173 + title="Active task endpoint"
174 + version="3.1"
175 + deprecated={deprecated}
176 + />,
177 + );
178 +
179 + expect(deprecated).toBe(false);
180 + expect(html).not.toContain(">Legacy</span>");
181 + });
182 +
183 test("serializes legacy only for deprecated v3.1 and v3 operations", async () => {
184 const fixtureDir = await generateFixture();
185 const v31Content = await readFile(