Do not document undocumented APIs (#1266)

* fix: strip internal x-undocumented fields from Mintlify OpenAPI spec

The transform pipeline only filtered operation-level x-undocumented,
removing whole undocumented paths. Schema-level markers leaked through:
the internal `sync` field (tagged `x-undocumented: "Only used
internally."`) shipped into the published spec as both a request-body
property and a query parameter on delete endpoints.

Add a recursive pass over the whole spec that removes any property or
parameter bearing x-undocumented (and drops it from sibling `required`),
covering request bodies, parameters, and response schemas across all HTTP
methods -- not just the `post` operations the existing loop touches.

Policy for x-draft: keep the annotated node, consistent with the existing
operation-level policy of keeping x-draft paths in the navigation, but
strip the x-draft marker key so internal notes ("Early access.", "Needs
review.") do not ship. No downstream code reads either marker.

Verified against the current generated openapi.json: 88 x-undocumented
and 18 x-draft markers reduced to 0, the internal `sync` field removed
from both bodies and params, and unmarked siblings preserved.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D5RzvZ86DxrMzBKyhhEDaW

* ci: Generate docs

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Seam Bot <seambot@getseam.com>

Author: 3 people

mintlify-codegen/lib/report.ts

@@ -10,6 +10,9 @@ export const report: Metalsmith.Plugin = (_files, metalsmith) => {
 
   console.log(`\nDone!`)
   console.log(`  Removed undocumented paths: ${stats.removedPaths}`)
+  console.log(
+    `  Removed undocumented fields/params: ${stats.removedInternalFields}`,
+  )
   console.log(`  Total documented endpoints: ${stats.totalEndpoints}`)
   console.log(`  With code samples: ${stats.withCodeSamples}`)
   console.log(`  With scoped action_attempts: ${stats.withActionAttempts}`)

mintlify-codegen/lib/transform-spec.ts

@@ -273,6 +273,66 @@ function rewriteAllDescriptions(obj: any): void {
   }
 }
 
+/**
+ * Recursively strip internal-only and preview markers from schema fragments.
+ *
+ * transformSpec() removes whole operations flagged `x-undocumented`, but the
+ * marker also appears on individual request parameters, request-body
+ * properties, and response properties (e.g. the internal `sync` field, tagged
+ * `x-undocumented: "Only used internally."`). Those leak into the published
+ * spec unless stripped here.
+ *
+ * Policy, mirroring the operation-level handling above:
+ *   - `x-undocumented` — internal-only. Remove the annotated property or
+ *     parameter outright, and drop it from any sibling `required` list.
+ *   - `x-draft` — early-access/preview. Keep the annotated node (consistent
+ *     with keeping x-draft paths in the navigation), but delete the marker key
+ *     so its internal note ("Early access.", "Needs review.") does not ship.
+ */
+function stripInternalSchemaFragments(obj: any, stats: TransformStats): void {
+  if (obj == null || typeof obj !== 'object') return
+
+  if (Array.isArray(obj)) {
+    for (const item of obj) stripInternalSchemaFragments(item, stats)
+    return
+  }
+
+  // Drop object-schema properties flagged x-undocumented. Check before
+  // recursing, since recursion deletes the marker from surviving nodes.
+  if (obj.properties != null && typeof obj.properties === 'object') {
+    for (const [name, propSchema] of Object.entries(obj.properties) as any) {
+      if (propSchema?.['x-undocumented'] != null) {
+        delete obj.properties[name]
+        if (Array.isArray(obj.required)) {
+          obj.required = obj.required.filter((r: string) => r !== name)
+          if (obj.required.length === 0) delete obj.required
+        }
+        stats.removedInternalFields++
+      }
+    }
+  }
+
+  // Drop operation parameters flagged x-undocumented. The marker can sit on the
+  // parameter object itself or on its nested schema.
+  if (Array.isArray(obj.parameters)) {
+    const before = obj.parameters.length
+    obj.parameters = obj.parameters.filter(
+      (param: any) =>
+        param?.['x-undocumented'] == null &&
+        param?.schema?.['x-undocumented'] == null,
+    )
+    stats.removedInternalFields += before - obj.parameters.length
+  }
+
+  // Recurse into whatever remains, then drop residual markers on this node.
+  for (const value of Object.values(obj)) {
+    stripInternalSchemaFragments(value, stats)
+  }
+
+  delete obj['x-undocumented']
+  delete obj['x-draft']
+}
+
 /**
  * Truncate a description to the first paragraph or ~500 chars.
  * Avoids cutting inside markdown links, which would produce broken
@@ -353,6 +413,7 @@ export function transformSpec(
     withActionAttempts: 0,
     withoutCodeSamples: [] as string[],
     removedPaths: 0,
+    removedInternalFields: 0,
   }
 
   // Remove only undocumented paths to reduce spec size
@@ -485,6 +546,11 @@ export function transformSpec(
   // Transform component schemas
   transformComponents(spec)
 
+  // Strip internal-only ("x-undocumented") properties and parameters that the
+  // operation-level path filter above does not reach (e.g. the internal `sync`
+  // field), and drop preview ("x-draft") markers from surviving nodes.
+  stripInternalSchemaFragments(spec, stats)
+
   // Recursively rewrite all description fields in the entire spec.
   // This catches deeply nested descriptions that the per-operation and
   // per-component passes above don't reach (e.g., parameter descriptions,
@@ -571,4 +637,5 @@ export interface TransformStats {
   withActionAttempts: number
   withoutCodeSamples: string[]
   removedPaths: number
+  removedInternalFields: number
 }