@devries-cameron20 / composio Mirror · read-only / commits / e53db1823
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, 13:30 UTC

fix(docs): hide deprecated fields from API reference

Brendan O'Leary committed Sep 9, 2026 at 16:13 UTC e53db1823fe18385a0511f9878e127d1d69ccc34
3 files changed +362 -1
docs/lib/openapi-deprecated.ts new
+186
@@ -0,0 +1,186 @@
1 +import { z } from 'zod';
2 +
3 +const ObjectSchema = z.record(z.string(), z.unknown());
4 +const Schema = z
5 + .object({
6 + $ref: z.string().optional(),
7 + deprecated: z.boolean().optional(),
8 + properties: z.record(z.string(), z.unknown()).optional(),
9 + required: z.array(z.string()).optional(),
10 + })
11 + .loose();
12 +
13 +// These are payloads, not schemas. In particular, a payload may legitimately
14 +// contain properties named "deprecated" or "properties".
15 +const PAYLOAD_KEYS = new Set(['default', 'example', 'examples', 'enum', 'const']);
16 +const SCHEMA_MAPS = new Set([
17 + 'properties',
18 + 'patternProperties',
19 + '$defs',
20 + 'definitions',
21 + 'dependentSchemas',
22 +]);
23 +const SCHEMA_LISTS = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);
24 +const SCHEMA_CHILDREN = new Set([
25 + 'items',
26 + 'additionalProperties',
27 + 'contains',
28 + 'not',
29 + 'if',
30 + 'then',
31 + 'else',
32 + 'propertyNames',
33 + 'unevaluatedProperties',
34 +]);
35 +
36 +/** Filter only the copy used by the docs; keep the published API contract intact. */
37 +export function hideDeprecatedFields<T extends object>(input: T): T {
38 + const document = structuredClone(input);
39 + function object(value: unknown) {
40 + const parsed = ObjectSchema.safeParse(value);
41 + if (!parsed.success) return undefined;
42 + return parsed.data;
43 + }
44 +
45 + function resolvePointer(ref: string): unknown {
46 + if (!ref.startsWith('#/')) return undefined;
47 + let value: unknown = input;
48 + for (const part of ref.slice(2).split('/')) {
49 + value = object(value)?.[decodeURIComponent(part).replace(/~1/g, '/').replace(/~0/g, '~')];
50 + }
51 + return value;
52 + }
53 +
54 + function resolve(value: unknown, seen = new Set<string>()): z.infer<typeof Schema> | undefined {
55 + const parsed = Schema.safeParse(value);
56 + if (!parsed.success) return undefined;
57 + const schema = parsed.data;
58 + if (!schema.$ref || seen.has(schema.$ref)) return schema;
59 + seen.add(schema.$ref);
60 + return { ...resolve(resolvePointer(schema.$ref), seen), ...schema };
61 + }
62 +
63 + function schemaVariants(value: unknown, seen = new Set<unknown>()): z.infer<typeof Schema>[] {
64 + if (seen.has(value)) return [];
65 + seen.add(value);
66 + const schema = resolve(value);
67 + if (!schema) return [];
68 + return [
69 + schema,
70 + ...['allOf', 'anyOf', 'oneOf'].flatMap(key => {
71 + const variants = schema[key];
72 + return Array.isArray(variants) ? variants.flatMap(item => schemaVariants(item, seen)) : [];
73 + }),
74 + ];
75 + }
76 +
77 + function properties(value: unknown) {
78 + const result = new Map<string, unknown[]>();
79 + for (const schema of schemaVariants(value)) {
80 + for (const [name, child] of Object.entries(schema.properties ?? {})) {
81 + result.set(name, [...(result.get(name) ?? []), child]);
82 + }
83 + }
84 + return result;
85 + }
86 +
87 + const allDeprecated = (schemas: unknown[]) =>
88 + schemas.every(schema => resolve(schema)?.deprecated === true);
89 +
90 + // Inspect the original schemas, which still contain the deprecation flags.
91 + // If a union also defines a current field with this name, preserve its value.
92 + function cleanValue(value: unknown, rawSchema: unknown): unknown {
93 + if (Array.isArray(value)) {
94 + const items = schemaVariants(rawSchema)
95 + .map(schema => schema.items)
96 + .filter(item => item !== undefined);
97 + return value.map(item => cleanValue(item, { allOf: items }));
98 + }
99 + const record = object(value);
100 + if (!record) return value;
101 + for (const [name, children] of properties(rawSchema)) {
102 + if (allDeprecated(children)) delete record[name];
103 + else if (Object.hasOwn(record, name))
104 + record[name] = cleanValue(record[name], { allOf: children });
105 + }
106 + return record;
107 + }
108 +
109 + function filterSchema(value: unknown): unknown {
110 + const parsed = Schema.safeParse(value);
111 + if (!parsed.success) return value; // Boolean schemas are valid in OpenAPI 3.1.
112 + const schema = parsed.data;
113 + if (schema.properties) {
114 + const hidden = new Set(
115 + Object.entries(schema.properties)
116 + .filter(([, child]) => resolve(child)?.deprecated === true)
117 + .map(([name]) => name)
118 + );
119 + schema.properties = Object.fromEntries(
120 + Object.entries(schema.properties)
121 + .filter(([name]) => !hidden.has(name))
122 + .map(([name, child]) => [name, filterSchema(child)])
123 + );
124 + }
125 + if (schema.required) {
126 + const fields = properties(value);
127 + schema.required = schema.required.filter(name => {
128 + const definitions = fields.get(name);
129 + return !definitions || !allDeprecated(definitions);
130 + });
131 + }
132 + for (const [key, child] of Object.entries(schema)) {
133 + if (key === 'default' || key === 'example') schema[key] = cleanValue(child, value);
134 + else if (key === 'examples' && Array.isArray(child))
135 + schema[key] = child.map(item => cleanValue(item, value));
136 + else if (key !== 'properties' && SCHEMA_MAPS.has(key)) {
137 + const map = object(child);
138 + if (map)
139 + schema[key] = Object.fromEntries(
140 + Object.entries(map).map(([name, item]) => [name, filterSchema(item)])
141 + );
142 + } else if (SCHEMA_LISTS.has(key) && Array.isArray(child))
143 + schema[key] = child.map(filterSchema);
144 + else if (SCHEMA_CHILDREN.has(key)) schema[key] = filterSchema(child);
145 + }
146 + return schema;
147 + }
148 +
149 + function walk(value: unknown, key = ''): unknown {
150 + if (Array.isArray(value)) return value.map(item => walk(item));
151 + const record = object(value);
152 + if (!record) return value;
153 + for (const [name, child] of Object.entries(record)) {
154 + if (name === 'schema') record[name] = filterSchema(child);
155 + else if (key === 'components' && name === 'schemas') {
156 + const schemas = object(child);
157 + if (schemas)
158 + record[name] = Object.fromEntries(
159 + Object.entries(schemas).map(([id, schema]) => [id, filterSchema(schema)])
160 + );
161 + } else if (!PAYLOAD_KEYS.has(name) && !name.startsWith('x-'))
162 + record[name] = walk(child, name);
163 + }
164 + if (record.schema) {
165 + if (Object.hasOwn(record, 'example'))
166 + record.example = cleanValue(record.example, object(value)?.schema);
167 + const examples = object(record.examples);
168 + if (examples) {
169 + record.examples = Object.fromEntries(
170 + Object.entries(examples).map(([name, entry]) => {
171 + const example = resolve(entry);
172 + if (example && Object.hasOwn(example, 'value')) {
173 + example.value = cleanValue(example.value, object(value)?.schema);
174 + delete example.$ref; // Inline this usage so shared examples remain unchanged.
175 + }
176 + return [name, example ?? entry];
177 + })
178 + );
179 + }
180 + }
181 + return record;
182 + }
183 +
184 + Object.assign(document, walk(document));
185 + return document;
186 +}
docs/lib/openapi.ts
+2 -1
@@ -1,5 +1,6 @@
1 import { readFile } from 'node:fs/promises';
2 import { join } from 'path';
3 +import { hideDeprecatedFields } from './openapi-deprecated';
4 import { createOpenAPI } from 'fumadocs-openapi/server';
5 import { declareOperationTags, type OpenAPIDocument } from './openapi-tags';
6
@@ -34,7 +35,7 @@ export const openapiV3 = createOpenAPI({
35
36 async function loadOpenAPISchema(path: string) {
37 const document = JSON.parse(await readFile(path, 'utf8')) as OpenAPIDocument;
37 - return declareOperationTags(normalizeNoAuthSecurity(document));
38 + return declareOperationTags(normalizeNoAuthSecurity(hideDeprecatedFields(document)));
39 }
40
41 export function normalizeNoAuthSecurity<T extends OpenAPIDocument>(document: T): T {
docs/tests/static/openapi-deprecated.test.ts new
+174
@@ -0,0 +1,174 @@
1 +import { describe, expect, test } from 'bun:test';
2 +import { readFileSync } from 'node:fs';
3 +import { join } from 'node:path';
4 +import { hideDeprecatedFields } from '../../lib/openapi-deprecated';
5 +import { openapi, openapiV3 } from '../../lib/openapi';
6 +
7 +describe('docs OpenAPI deprecation filter', () => {
8 + test('removes fields and their values while preserving the source and legacy operations', () => {
9 + const schema = {
10 + type: 'object',
11 + properties: {
12 + current: { type: 'string' },
13 + old: { deprecated: true },
14 + nested: { type: 'array', items: { properties: { old: { deprecated: true }, keep: {} } } },
15 + metadata: { type: 'object', additionalProperties: true },
16 + },
17 + required: ['current', 'old'],
18 + default: {
19 + current: 'yes',
20 + old: 'no',
21 + nested: [{ old: 1, keep: 2 }],
22 + metadata: { deprecated: true },
23 + },
24 + };
25 + const source = {
26 + paths: {
27 + '/test': {
28 + post: {
29 + deprecated: true,
30 + requestBody: {
31 + content: {
32 + 'application/json': {
33 + schema,
34 + example: schema.default,
35 + examples: { named: { value: schema.default } },
36 + },
37 + },
38 + },
39 + },
40 + },
41 + },
42 + };
43 + const original = structuredClone(source);
44 + const result = hideDeprecatedFields(source);
45 + const media = result.paths['/test'].post.requestBody.content['application/json'];
46 + const expected = { current: 'yes', nested: [{ keep: 2 }], metadata: { deprecated: true } };
47 + expect(media.schema.properties).not.toHaveProperty('old');
48 + expect(media.schema.required).toEqual(['current']);
49 + expect(media.schema.default).toEqual(expected);
50 + expect(media.example).toEqual(expected);
51 + expect(media.examples.named.value).toEqual(expected);
52 + expect(result.paths['/test'].post.deprecated).toBe(true);
53 + expect(source).toEqual(original);
54 + expect(hideDeprecatedFields(result)).toEqual(result);
55 + });
56 +
57 + test('handles references, aliases, compositions, recursion and boolean schemas', () => {
58 + const source = {
59 + components: {
60 + schemas: {
61 + 'Old/Field': { deprecated: true },
62 + Alias: { $ref: '#/components/schemas/Old~1Field' },
63 + Recursive: {
64 + properties: {
65 + old: { deprecated: true },
66 + next: { $ref: '#/components/schemas/Recursive' },
67 + },
68 + },
69 + Composed: {
70 + allOf: [{ properties: { old: { deprecated: true }, keep: true }, required: ['old'] }],
71 + },
72 + Root: {
73 + properties: {
74 + alias: { $ref: '#/components/schemas/Alias' },
75 + retained: { $ref: '#/components/schemas/Alias', deprecated: false },
76 + recursive: { $ref: '#/components/schemas/Recursive' },
77 + external: { $ref: 'https://example.com/schema.json' },
78 + boolean: true,
79 + },
80 + default: { alias: 1, retained: 2, recursive: { old: 1, next: { old: 2 } } },
81 + },
82 + },
83 + },
84 + };
85 + const result = hideDeprecatedFields(source).components.schemas;
86 + expect(result.Root.properties).not.toHaveProperty('alias');
87 + expect(result.Root.properties.retained).toEqual(
88 + source.components.schemas.Root.properties.retained
89 + );
90 + expect(result.Root.properties.external).toEqual(
91 + source.components.schemas.Root.properties.external
92 + );
93 + expect(result.Root.properties.boolean).toBe(true);
94 + expect(result.Root.default).toEqual({ retained: 2, recursive: { next: {} } });
95 + expect(result.Recursive.properties).not.toHaveProperty('old');
96 + expect(result.Composed.allOf[0].properties).toEqual({ keep: true });
97 + expect(result.Composed.allOf[0].required).toEqual([]);
98 + });
99 +
100 + test('cleans composed requirements and referenced examples without deleting current union fields', () => {
101 + const source = {
102 + components: { examples: { shared: { value: { old: 1, keep: 2 } } } },
103 + paths: {
104 + '/test': {
105 + post: {
106 + requestBody: {
107 + content: {
108 + 'application/json': {
109 + schema: {
110 + allOf: [{ properties: { old: { deprecated: true }, keep: {} } }],
111 + required: ['old', 'keep'],
112 + },
113 + examples: { sample: { $ref: '#/components/examples/shared' } },
114 + },
115 + },
116 + },
117 + },
118 + },
119 + },
120 + };
121 + const result = hideDeprecatedFields(source);
122 + const media = result.paths['/test'].post.requestBody.content['application/json'];
123 + expect(media.schema.required).toEqual(['keep']);
124 + expect(media.examples.sample).toEqual({ value: { keep: 2 } });
125 + expect(result.components.examples.shared.value).toEqual({ old: 1, keep: 2 });
126 + const union = {
127 + components: {
128 + schemas: {
129 + Union: {
130 + oneOf: [{ properties: { field: { deprecated: true } } }, { properties: { field: {} } }],
131 + default: { field: 'still supported' },
132 + },
133 + },
134 + },
135 + };
136 + expect(hideDeprecatedFields(union).components.schemas.Union.default).toEqual({
137 + field: 'still supported',
138 + });
139 + });
140 +
141 + test('does not treat examples or extension values as schema definitions', () => {
142 + const payload = { schema: { properties: { old: { deprecated: true } } } };
143 + const source = { example: payload, 'x-custom': payload };
144 + expect(hideDeprecatedFields(source)).toEqual(source);
145 + });
146 +
147 + test('filters the actual documents consumed by both schema UI and playground', async () => {
148 + for (const server of [openapi, openapiV3]) {
149 + const schemas = await server.getSchemas();
150 + for (const [path, { bundled }] of Object.entries(schemas)) {
151 + if (path.endsWith('openapi-webhooks.json')) continue;
152 + const managed = bundled.components?.schemas?.ComposioManagedAuthConfigCreate;
153 + expect(managed).toHaveProperty('properties.credentials');
154 + expect(managed).not.toHaveProperty('properties.tool_access_config');
155 + expect(managed).not.toHaveProperty('properties.restrict_to_following_tools');
156 + expect(bundled.components?.schemas?.CustomAuthConfigCreate).not.toHaveProperty(
157 + 'properties.tool_access_config'
158 + );
159 + const operation = Object.values(bundled.paths ?? {})
160 + .flatMap(item => item?.post ?? [])
161 + .find(
162 + item =>
163 + item.operationId === 'postAuthConfigs' || item.operationId === 'postApiV3AuthConfigs'
164 + );
165 + expect(operation).toBeDefined();
166 + expect(JSON.stringify(operation?.requestBody)).not.toContain('restrict_to_following_tools');
167 + }
168 + }
169 + // The downloadable contract remains complete on disk.
170 + expect(readFileSync(join(process.cwd(), 'public/openapi.json'), 'utf8')).toContain(
171 + '"restrict_to_following_tools"'
172 + );
173 + });
174 +});