Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 18:30 UTC
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(