@devries-cameron20 / composio Mirror · read-only / commits / 5078481dc
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 18:30 UTC

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 +});