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