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 (#3911)
This PR: - follows up on https://github.com/ComposioHQ/composio/pull/3838 - renders the existing `Legacy` badge in v3 and v3.1 endpoint headers when the OpenAPI operation has `deprecated: true` - centralizes deprecated-endpoint badge copy across API overview tables and detail pages - adds static coverage plus running-server assertions for the reported routes and active control endpoints - verifies the fix with `bun run test`, `bun run types:check`, `bun run lint:links`, `bun run build`, and the focused integration suite
Alberto Schiabel committed
Jul 23, 2026 at 14:17 UTC
5078481dcc74dd67749700c825e7e5614c7b20a9
15 files changed
+485
-36
docs/app/(home)/docs/[[...slug]]/page.tsx
+1
-1
@@ -46,7 +46,7 @@ export default async function Page(props: PageProps<'/docs/[[...slug]]'>) {
46
)}
47
</div>
48
)}
49
- {data.experimental && <ExperimentalBadge />}
49
+ {data.experimental && <ExperimentalBadge className="mb-3" />}
50
<DocsTitle>{data.title}</DocsTitle>
51
<PageActions path={page.url} />
52
</>
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
+6
-5
@@ -1,7 +1,8 @@
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
+import { getApiDisplayTitle } from '@/lib/api-deprecation';
6
7
interface Endpoint {
8
method: string;
@@ -36,12 +37,12 @@ export function ApiEndpointsTable({ endpoints }: { endpoints: Endpoint[] }) {
37
<tr key={i}>
38
<td><code>{ep.method} {path}</code></td>
39
<td>
39
- <a href={ep.href}>{ep.summary}</a>
40
+ <a href={ep.href}>
41
+ {getApiDisplayTitle(ep.summary, ep.legacy === true)}
42
+ </a>
43
{ep.legacy && (
44
<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
- />
45
+ <DeprecatedApiLegacyBadge />
46
</span>
47
)}
48
</td>
docs/components/api-page-title.tsx
new
+29
@@ -0,0 +1,29 @@
1
+import { DeprecatedApiLegacyBadge } from '@/components/legacy-badge';
2
+import { VersionBadge } from '@/components/version-badge';
3
+import { getApiDisplayTitle } from '@/lib/api-deprecation';
4
+
5
+interface ApiPageTitleProps {
6
+ title: string;
7
+ version: string | null;
8
+ deprecated: boolean;
9
+}
10
+
11
+export function ApiPageTitle({
12
+ title,
13
+ version,
14
+ deprecated,
15
+}: ApiPageTitleProps) {
16
+ const displayTitle = getApiDisplayTitle(title, deprecated);
17
+
18
+ return (
19
+ <h1 className="flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1 text-2xl font-semibold">
20
+ <span>{displayTitle}</span>
21
+ {(version || deprecated) && (
22
+ <span className="inline-flex shrink-0 items-center gap-2">
23
+ {version && <VersionBadge version={version} />}
24
+ {deprecated && <DeprecatedApiLegacyBadge />}
25
+ </span>
26
+ )}
27
+ </h1>
28
+ );
29
+}
docs/components/custom-schema-ui.tsx
+2
@@ -9,6 +9,7 @@ import {
9
import { cn } from '@/lib/utils';
10
import { Plus, X } from 'lucide-react';
11
import type { SchemaData, SchemaUIGeneratedData } from './schema-generator';
12
+import { ExperimentalBadge } from './experimental-badge';
13
14
interface SchemaUIProps {
15
name: string;
@@ -148,6 +149,7 @@ function SchemaProperty({
149
Deprecated
150
</span>
151
)}
152
+ {schema.experimental && <ExperimentalBadge />}
153
</div>
154
155
{/* Description */}
docs/components/experimental-badge.tsx
+10
-6
@@ -1,14 +1,18 @@
1
+import { cn } from '@/lib/utils';
2
+
3
/**
2
- * "Experimental" badge rendered at the top of a docs page (under the title)
3
- * when the page frontmatter sets `experimental: true`. Signals that the page's
4
- * APIs may change in future releases, so individual pages don't need an inline
5
- * callout saying the same thing.
4
+ * Shared lifecycle badge for experimental docs pages and API schema fields.
5
+ * Spacing is caller-owned so it works both above a page title and inline with
6
+ * a field name.
7
*/
7
-export function ExperimentalBadge() {
8
+export function ExperimentalBadge({ className }: { className?: string }) {
9
return (
10
<span
11
title="Experimental: these APIs may change in future releases"
11
- className="not-prose mb-3 inline-flex w-fit items-center gap-1.5 rounded-md border border-amber-600/20 bg-amber-100 px-2 py-0.5 text-xs font-medium uppercase tracking-wide text-amber-700 dark:border-amber-500/25 dark:bg-amber-500/10 dark:text-amber-400"
12
+ className={cn(
13
+ 'not-prose inline-flex w-fit items-center gap-1.5 rounded-md border border-amber-600/20 bg-amber-100 px-2 py-0.5 text-xs font-medium uppercase tracking-wide text-amber-700 dark:border-amber-500/25 dark:bg-amber-500/10 dark:text-amber-400',
14
+ className
15
+ )}
16
>
17
Experimental
18
</span>
docs/components/legacy-badge.tsx
+21
-1
@@ -1,3 +1,5 @@
1
+import { cn } from '@/lib/utils';
2
+
3
/**
4
* "Legacy" badge rendered at the top of a docs page (under the title) when the
5
* page frontmatter sets `legacy: true` — for guides superseded by sessions but
@@ -7,17 +9,35 @@
9
*/
10
interface LegacyBadgeProps {
11
title?: string;
12
+ className?: string;
13
}
14
15
+export const DEPRECATED_API_LEGACY_TITLE =
16
+ 'Deprecated API endpoint; kept for existing integrations and may be removed in a future release';
17
+
18
export function LegacyBadge({
19
title = 'Legacy: superseded by sessions; kept for existing integrations',
20
+ className,
21
}: LegacyBadgeProps) {
22
return (
23
<span
24
title={title}
18
- className="not-prose inline-flex w-fit items-center gap-1.5 rounded-md border border-fd-border bg-fd-muted px-2 py-0.5 text-xs font-medium uppercase tracking-wide text-fd-muted-foreground"
25
+ className={cn(
26
+ 'not-prose inline-flex w-fit items-center gap-1.5 rounded-md border border-fd-border bg-fd-muted px-2 py-0.5 text-xs font-medium uppercase tracking-wide text-fd-muted-foreground',
27
+ className
28
+ )}
29
>
30
Legacy
31
</span>
32
);
33
}
34
+
35
+export function DeprecatedApiLegacyBadge({ className }: { className?: string }) {
36
+ return <LegacyBadge title={DEPRECATED_API_LEGACY_TITLE} className={className} />;
37
+}
38
+
39
+export function DeprecatedApiSidebarLegacyBadge() {
40
+ return (
41
+ <DeprecatedApiLegacyBadge className="ml-1 align-middle rounded px-1.5 py-px text-[10px]" />
42
+ );
43
+}
docs/components/schema-generator.tsx
+20
-1
@@ -7,6 +7,7 @@ interface FieldBase {
7
typeName: string;
8
aliasName: string;
9
deprecated?: boolean;
10
+ experimental?: boolean;
11
enumValues?: string[];
12
}
13
@@ -44,6 +45,20 @@ interface SchemaUIOptions {
45
writeOnly?: boolean;
46
}
47
48
+/**
49
+ * Removes the source-level marker when the schema provides a structured
50
+ * experimental flag. Unflagged descriptions keep their original text so they
51
+ * do not lose their only lifecycle signal.
52
+ */
53
+export function getSchemaDisplayDescription(
54
+ description: string,
55
+ experimental: boolean,
56
+): string {
57
+ if (!experimental) return description;
58
+
59
+ return description.replace(/^\s*\[experimental\]\s*/i, '');
60
+}
61
+
62
export function generateSchemaData(
63
options: SchemaUIOptions,
64
ctx: RenderContext
@@ -119,14 +134,18 @@ export function generateSchemaData(
134
? getTypeName(schema.items)
135
: getTypeName(schema);
136
137
+ const experimental = schema['x-experimental'] === true;
138
const base: FieldBase = {
139
description: schema.description
124
- ? ctx.renderMarkdown(schema.description)
140
+ ? ctx.renderMarkdown(
141
+ getSchemaDisplayDescription(schema.description, experimental),
142
+ )
143
: undefined,
144
infoTags: generateInfoTags(schema),
145
typeName: getTypeName(schema),
146
aliasName,
147
deprecated: schema.deprecated,
148
+ experimental,
149
enumValues: schema.enum
150
? schema.enum.map((v: unknown) => String(v))
151
: undefined,
docs/lib/api-deprecation.ts
new
+43
@@ -0,0 +1,43 @@
1
+export 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
+ * Removes the source-level deprecation suffix when a structured lifecycle
19
+ * badge is rendered alongside the title. Other contexts keep the raw OpenAPI
20
+ * title so they do not lose their only deprecation signal.
21
+ */
22
+export function getApiDisplayTitle(title: string, deprecated: boolean): string {
23
+ if (!deprecated) return title;
24
+
25
+ return title.replace(/\s+\(deprecated\)\s*$/i, '');
26
+}
27
+
28
+/**
29
+ * Returns whether any operation rendered by an OpenAPI page is deprecated.
30
+ * Operation detail pages currently contain one operation, but checking all of
31
+ * them keeps the helper correct for grouped pages too.
32
+ */
33
+export function isApiPageDeprecated(
34
+ pageData: OpenApiSchemaPageData,
35
+ operations?: ApiPageOperation[],
36
+): boolean {
37
+ if (!operations || operations.length === 0) return false;
38
+
39
+ const paths = pageData.getSchema().dereferenced.paths;
40
+ return operations.some(
41
+ ({ method, path }) => paths?.[path]?.[method]?.deprecated === true,
42
+ );
43
+}
docs/lib/deprecated-api-sidebar.tsx
new
+59
@@ -0,0 +1,59 @@
1
+import type { ReactNode } from 'react';
2
+import type { Item } from 'fumadocs-core/page-tree';
3
+import type { PageTreeTransformer } from 'fumadocs-core/source';
4
+import { DeprecatedApiSidebarLegacyBadge } from '@/components/legacy-badge';
5
+import { getApiDisplayTitle, isApiPageDeprecated } from '@/lib/api-deprecation';
6
+import type { ApiPageOperation, OpenApiSchemaPageData } from '@/lib/api-deprecation';
7
+
8
+interface OpenApiSidebarPageData extends OpenApiSchemaPageData {
9
+ title: string;
10
+ getAPIPageProps: () => {
11
+ operations?: ApiPageOperation[];
12
+ };
13
+}
14
+
15
+function isOpenApiSidebarPageData(data: unknown): data is OpenApiSidebarPageData {
16
+ if (!data || typeof data !== 'object') return false;
17
+
18
+ const candidate = data as Partial<OpenApiSidebarPageData>;
19
+ return (
20
+ typeof candidate.title === 'string' &&
21
+ typeof candidate.getSchema === 'function' &&
22
+ typeof candidate.getAPIPageProps === 'function'
23
+ );
24
+}
25
+
26
+export function getDeprecatedApiSidebarName(
27
+ title: string,
28
+ pageData: OpenApiSchemaPageData,
29
+ operations?: ApiPageOperation[]
30
+): ReactNode {
31
+ if (!isApiPageDeprecated(pageData, operations)) return title;
32
+
33
+ return (
34
+ <span className="min-w-0">
35
+ {getApiDisplayTitle(title, true)} <DeprecatedApiSidebarLegacyBadge />
36
+ </span>
37
+ );
38
+}
39
+
40
+/**
41
+ * Replaces a deprecated OpenAPI operation's textual title suffix with a
42
+ * compact lifecycle badge before fumadocs-openapi appends its method label.
43
+ */
44
+export const deprecatedApiSidebarTransformer: PageTreeTransformer = {
45
+ file(node: Item, filePath?: string): Item {
46
+ if (!filePath) return node;
47
+
48
+ const file = this.storage.read(filePath);
49
+ if (!file || file.format !== 'page' || !isOpenApiSidebarPageData(file.data)) {
50
+ return node;
51
+ }
52
+
53
+ const apiProps = file.data.getAPIPageProps();
54
+ return {
55
+ ...node,
56
+ name: getDeprecatedApiSidebarName(file.data.title, file.data, apiProps.operations),
57
+ };
58
+ },
59
+};
docs/lib/source.ts
+5
-1
@@ -6,6 +6,7 @@ import { openapiSource, openapiPlugin } from 'fumadocs-openapi/server';
6
import { getGuardrails } from './llm-guardrails';
7
import { HIDDEN_API_TAGS } from './filter-api-version';
8
import { FILE_BUILDS } from './file-builds';
9
+import { deprecatedApiSidebarTransformer } from './deprecated-api-sidebar';
10
11
/**
12
* True if a reference URL belongs to an intentionally-hidden API tag
@@ -82,7 +83,10 @@ export async function getReferenceSource() {
83
plugins: [lucideIconsPlugin(), openapiPlugin()],
84
pageTree: {
85
// eslint-disable-next-line @typescript-eslint/no-explicit-any
85
- transformers: [defaultOpenTransformer as any],
86
+ transformers: [
87
+ defaultOpenTransformer as any,
88
+ deprecatedApiSidebarTransformer as any,
89
+ ],
90
},
91
});
92
docs/tests/integration/rendering.test.ts
+61
@@ -19,6 +19,25 @@ 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
+function getPageHeading(html: string): string | undefined {
38
+ return html.match(/<h1[^>]*>[\s\S]*?<\/h1>/)?.[0];
39
+}
40
+
41
describe("Page rendering - critical pages", () => {
42
for (const { path, name } of CRITICAL_PAGES) {
43
test(`${name} (${path}) returns 200`, async () => {
@@ -56,6 +75,48 @@ describe("Page rendering - content markers", () => {
75
});
76
});
77
78
+describe("Page rendering - deprecated API endpoints", () => {
79
+ for (const path of DEPRECATED_API_PAGES) {
80
+ test(`${path} renders the Legacy badge`, async () => {
81
+ const res = await fetchPage(path);
82
+ const html = await res.text();
83
+ const heading = getPageHeading(html);
84
+
85
+ expect(res.status).toBe(200);
86
+ expect(heading).toBeDefined();
87
+ expect(heading).toContain(DEPRECATED_API_LEGACY_TITLE);
88
+ });
89
+ }
90
+
91
+ for (const path of ACTIVE_API_PAGES) {
92
+ test(`${path} omits the Legacy badge`, async () => {
93
+ const res = await fetchPage(path);
94
+ const html = await res.text();
95
+ const heading = getPageHeading(html);
96
+
97
+ expect(res.status).toBe(200);
98
+ expect(heading).toBeDefined();
99
+ expect(heading).not.toContain(DEPRECATED_API_LEGACY_TITLE);
100
+ });
101
+ }
102
+
103
+ test("deprecated endpoint sidebar links replace the title marker with Legacy", async () => {
104
+ const path = DEPRECATED_API_PAGES[0];
105
+ const res = await fetchPage(path);
106
+ const html = await res.text();
107
+ const escapedPath = path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
108
+ const sidebarLink = html.match(
109
+ new RegExp(`<a[^>]*href="${escapedPath}"[^>]*>[\\s\\S]*?<\\/a>`),
110
+ )?.[0];
111
+
112
+ expect(res.status).toBe(200);
113
+ expect(sidebarLink).toBeDefined();
114
+ expect(sidebarLink).toContain(">Legacy</span>");
115
+ expect(sidebarLink).not.toContain("(DEPRECATED)");
116
+ expect(sidebarLink).toContain(">POST</span>");
117
+ });
118
+});
119
+
120
describe("Page rendering - error handling", () => {
121
test("non-existent page returns 404", async () => {
122
const res = await fetchPage("/docs/this-page-does-not-exist-ever");
docs/tests/static/api-deprecation.test.tsx
+152
-1
@@ -9,6 +9,10 @@ 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 { DEPRECATED_API_LEGACY_TITLE } = await import("../../components/legacy-badge");
14
+const { getDeprecatedApiSidebarName } = await import("../../lib/deprecated-api-sidebar");
15
+const { getApiDisplayTitle, isApiPageDeprecated } = await import("../../lib/api-deprecation");
16
17
const DOCS_DIR = join(import.meta.dir, "../..");
18
const GENERATOR_PATH = join(DOCS_DIR, "scripts/generate-api-index.ts");
@@ -115,6 +119,149 @@ afterEach(async () => {
119
});
120
121
describe("deprecated API endpoints", () => {
122
+ test("removes only a trailing deprecation marker from deprecated display titles", () => {
123
+ expect(getApiDisplayTitle("Deprecated task endpoint (DEPRECATED)", true)).toBe(
124
+ "Deprecated task endpoint",
125
+ );
126
+ expect(getApiDisplayTitle("Deprecated task endpoint (deprecated)", true)).toBe(
127
+ "Deprecated task endpoint",
128
+ );
129
+ expect(getApiDisplayTitle("Active task endpoint (DEPRECATED)", false)).toBe(
130
+ "Active task endpoint (DEPRECATED)",
131
+ );
132
+ expect(getApiDisplayTitle("Deprecated endpoint details", true)).toBe(
133
+ "Deprecated endpoint details",
134
+ );
135
+ });
136
+
137
+ test("renders Legacy on a deprecated API endpoint detail title", () => {
138
+ const operation = {
139
+ method: "get",
140
+ path: "/v3.1/tasks/deprecated",
141
+ };
142
+ const pageData = {
143
+ getSchema: () => ({
144
+ dereferenced: {
145
+ paths: {
146
+ [operation.path]: {
147
+ [operation.method]: { deprecated: true },
148
+ },
149
+ },
150
+ },
151
+ }),
152
+ };
153
+
154
+ const deprecated = isApiPageDeprecated(pageData, [operation]);
155
+ const html = renderToStaticMarkup(
156
+ <ApiPageTitle
157
+ title="Deprecated task endpoint (DEPRECATED)"
158
+ version="3.1"
159
+ deprecated={deprecated}
160
+ />,
161
+ );
162
+
163
+ expect(deprecated).toBe(true);
164
+ expect(html).toContain("<span>Deprecated task endpoint</span>");
165
+ expect(html).not.toContain("Deprecated task endpoint (DEPRECATED)");
166
+ expect(html).toContain(
167
+ 'class="flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1 text-2xl font-semibold"',
168
+ );
169
+ expect(html).toContain('class="inline-flex shrink-0 items-center gap-2"');
170
+ expect(html.match(/>Legacy<\/span>/g)).toHaveLength(1);
171
+ expect(html).toContain(
172
+ 'title="Deprecated API endpoint; kept for existing integrations and may be removed in a future release"',
173
+ );
174
+ });
175
+
176
+ test("omits Legacy from an active API endpoint detail title", () => {
177
+ const operation = {
178
+ method: "post",
179
+ path: "/v3.1/tasks/active",
180
+ };
181
+ const pageData = {
182
+ getSchema: () => ({
183
+ dereferenced: {
184
+ paths: {
185
+ [operation.path]: {
186
+ [operation.method]: {},
187
+ },
188
+ },
189
+ },
190
+ }),
191
+ };
192
+
193
+ const deprecated = isApiPageDeprecated(pageData, [operation]);
194
+ const html = renderToStaticMarkup(
195
+ <ApiPageTitle
196
+ title="Active task endpoint"
197
+ version="3.1"
198
+ deprecated={deprecated}
199
+ />,
200
+ );
201
+
202
+ expect(deprecated).toBe(false);
203
+ expect(html).not.toContain(">Legacy</span>");
204
+ });
205
+
206
+ test("replaces the sidebar title marker with a compact Legacy badge", () => {
207
+ const operation = {
208
+ method: "get",
209
+ path: "/v3.1/tasks/deprecated",
210
+ };
211
+ const pageData = {
212
+ getSchema: () => ({
213
+ dereferenced: {
214
+ paths: {
215
+ [operation.path]: {
216
+ [operation.method]: { deprecated: true },
217
+ },
218
+ },
219
+ },
220
+ }),
221
+ };
222
+
223
+ const html = renderToStaticMarkup(
224
+ <>
225
+ {getDeprecatedApiSidebarName("Deprecated task endpoint (DEPRECATED)", pageData, [
226
+ operation,
227
+ ])}
228
+ </>,
229
+ );
230
+
231
+ expect(html).toContain("Deprecated task endpoint");
232
+ expect(html).not.toContain("(DEPRECATED)");
233
+ expect(html.match(/>Legacy<\/span>/g)).toHaveLength(1);
234
+ expect(html).toContain("text-[10px]");
235
+ expect(html).toContain(DEPRECATED_API_LEGACY_TITLE);
236
+ });
237
+
238
+ test("keeps an unflagged sidebar title unchanged", () => {
239
+ const operation = {
240
+ method: "post",
241
+ path: "/v3.1/tasks/active",
242
+ };
243
+ const pageData = {
244
+ getSchema: () => ({
245
+ dereferenced: {
246
+ paths: {
247
+ [operation.path]: {
248
+ [operation.method]: {},
249
+ },
250
+ },
251
+ },
252
+ }),
253
+ };
254
+
255
+ const html = renderToStaticMarkup(
256
+ <>
257
+ {getDeprecatedApiSidebarName("Active task endpoint (DEPRECATED)", pageData, [operation])}
258
+ </>,
259
+ );
260
+
261
+ expect(html).toBe("Active task endpoint (DEPRECATED)");
262
+ expect(html).not.toContain(">Legacy</span>");
263
+ });
264
+
265
test("serializes legacy only for deprecated v3.1 and v3 operations", async () => {
266
const fixtureDir = await generateFixture();
267
const v31Content = await readFile(
@@ -147,7 +294,7 @@ describe("deprecated API endpoints", () => {
294
method: "GET",
295
pathV31: "/v3.1/tasks/deprecated",
296
pathV3: "/v3/tasks/deprecated",
150
- summary: "Deprecated task endpoint",
297
+ summary: "Deprecated task endpoint (DEPRECATED)",
298
href: "/reference/api-reference/tasks/getDeprecatedTask",
299
legacy: true,
300
},
@@ -162,6 +309,10 @@ describe("deprecated API endpoints", () => {
309
/>,
310
);
311
312
+ expect(html).toContain(
313
+ '<a href="/reference/api-reference/tasks/getDeprecatedTask">Deprecated task endpoint</a>',
314
+ );
315
+ expect(html).not.toContain("Deprecated task endpoint (DEPRECATED)");
316
expect(
317
html.match(
318
/title="Deprecated API endpoint; kept for existing integrations and may be removed in a future release"/g,
docs/tests/static/api-schema-experimental.test.tsx
new
+54
@@ -0,0 +1,54 @@
1
+import { describe, expect, test } from 'bun:test';
2
+import { renderToStaticMarkup } from 'react-dom/server';
3
+
4
+import { CustomSchemaUI } from '../../components/custom-schema-ui';
5
+import { generateSchemaData, getSchemaDisplayDescription } from '../../components/schema-generator';
6
+
7
+describe('experimental API schema fields', () => {
8
+ test('removes only a leading marker from flagged descriptions', () => {
9
+ expect(
10
+ getSchemaDisplayDescription('[EXPERIMENTAL] Whether to validate credentials', true)
11
+ ).toBe('Whether to validate credentials');
12
+ expect(
13
+ getSchemaDisplayDescription('[Experimental] Whether to validate credentials', true)
14
+ ).toBe('Whether to validate credentials');
15
+ expect(getSchemaDisplayDescription('[EXPERIMENTAL] Unflagged source description', false)).toBe(
16
+ '[EXPERIMENTAL] Unflagged source description'
17
+ );
18
+ expect(getSchemaDisplayDescription('Experimental behavior without a source marker', true)).toBe(
19
+ 'Experimental behavior without a source marker'
20
+ );
21
+ });
22
+
23
+ test('renders one Experimental badge with clean field copy', () => {
24
+ const generated = generateSchemaData(
25
+ {
26
+ root: {
27
+ type: 'object',
28
+ properties: {
29
+ validate_credentials: {
30
+ type: 'boolean',
31
+ default: false,
32
+ description: '[EXPERIMENTAL] Whether to validate the provided credentials',
33
+ 'x-experimental': true,
34
+ },
35
+ },
36
+ },
37
+ },
38
+ {
39
+ renderMarkdown: text => text,
40
+ schema: { getRawRef: () => undefined },
41
+ }
42
+ );
43
+
44
+ const html = renderToStaticMarkup(
45
+ <CustomSchemaUI name="body" as="body" generated={generated} />
46
+ );
47
+
48
+ expect(html).toContain('validate_credentials');
49
+ expect(html.match(/>Experimental<\/span>/g)).toHaveLength(1);
50
+ expect(html).toContain('Whether to validate the provided credentials');
51
+ expect(html).not.toContain('[EXPERIMENTAL]');
52
+ expect(html).toContain('title="Experimental: these APIs may change in future releases"');
53
+ });
54
+});