Strip unused fields from REST schema.json pipeline (~32% size reduction) (#60279)

Author: Ebonsignori

src/article-api/liquid-renderers/rest-tags.ts

@@ -150,8 +150,6 @@ export class RestStatusCode {
       if (description.trim()) {
         lines.push(`  ${description.trim()}`)
       }
-    } else if (statusCode.httpStatusMessage) {
-      lines.push(`- **${statusCode.httpStatusCode}** - ${statusCode.httpStatusMessage}`)
     } else {
       lines.push(`- **${statusCode.httpStatusCode}**`)
     }

src/automated-pipelines/components/parameter-table/types.ts

@@ -11,7 +11,6 @@ export interface Parameter {
 }
 
 export interface BodyParameter {
-  in: string
   name: string
   description: string
   type: string

src/rest/components/RestStatusCodes.tsx

@@ -30,11 +30,7 @@ export function RestStatusCodes({ statusCodes, slug, heading }: Props) {
                 <code>{statusCode.httpStatusCode}</code>
               </td>
               <td>
-                {statusCode.description ? (
-                  <div dangerouslySetInnerHTML={{ __html: statusCode.description }} />
-                ) : (
-                  statusCode.httpStatusMessage
-                )}
+                <div dangerouslySetInnerHTML={{ __html: statusCode.description }} />
               </td>
             </tr>
           ))}

src/rest/components/types.ts

@@ -25,7 +25,6 @@ export interface ProgAccessT {
 }
 
 export interface Parameter {
-  exampleName?: string
   in: string
   name: string
   description: string
@@ -40,11 +39,9 @@ export interface Parameter {
 export interface StatusCode {
   description: string
   httpStatusCode: string
-  httpStatusMessage: string
 }
 
 export interface CodeSample {
-  key: string
   response: {
     contentType: string
     description: string
@@ -61,7 +58,6 @@ export interface CodeSample {
 }
 
 export interface BodyParameter {
-  in: string
   name: string
   description: string
   type: string

src/rest/scripts/utils/create-rest-examples.ts

@@ -31,7 +31,6 @@ interface ResponseExample {
 }
 
 interface MergedExample {
-  key: string
   request: {
     contentType?: string
     description: string
@@ -66,20 +65,23 @@ export default async function getCodeSamples(operation: Operation): Promise<Merg
       count[item.request.description] = (count[item.request.description] || 0) + 1
     }
 
-    const newMergedExamples = mergedExamples.map((example, i) => ({
-      ...example,
-      request: {
-        ...example.request,
-        description:
-          count[example.request.description] > 1
-            ? `${example.request.description} ${i + 1}: Status Code ${example.response!.statusCode}`
-            : example.request.description,
-      },
-    }))
-
-    return newMergedExamples
+    return mergedExamples.map((example, i) => {
+      delete (example as any).key
+      return {
+        ...example,
+        request: {
+          ...example.request,
+          description:
+            count[example.request.description] > 1
+              ? `${example.request.description} ${i + 1}: Status Code ${example.response!.statusCode}`
+              : example.request.description,
+        },
+      }
+    })
   }
 
+  // Strip the key field — it's only needed during merging, not at runtime
+  for (const example of mergedExamples) delete (example as any).key
   return mergedExamples
 }
 
@@ -260,6 +262,24 @@ export function getRequestExamples(operation: Operation): RequestExample[] {
   return requestExamples
 }
 
+/*
+  Recursively removes `example` and `examples` annotation fields from a JSON
+  Schema object. These fields are OpenAPI annotation-only and are never read
+  by the runtime rendering code, but they account for ~131 MB of the total
+  schema.json size across all versions.
+*/
+function stripSchemaExamples(schema: any): any {
+  if (!schema || typeof schema !== 'object') return schema
+  if (Array.isArray(schema)) return schema.map(stripSchemaExamples)
+
+  const result: any = {}
+  for (const [key, value] of Object.entries(schema)) {
+    if (key === 'example' || key === 'examples') continue
+    result[key] = stripSchemaExamples(value)
+  }
+  return result
+}
+
 /*
   Create an example object for each example in the response property
   of the schema. Each response can have more than one status code,
@@ -355,7 +375,10 @@ export function getResponseExamples(operation: Operation): ResponseExample[] {
             // Note: Including the schema significantly increases JSON file size (~4x),
             // but it's necessary to support the schema/example toggle in the UI.
             // Users can switch between viewing the example response and the full schema.
-            schema: operation.responses[statusCode].content[contentType].schema,
+            // example/examples annotation fields are stripped as they are not rendered.
+            schema: stripSchemaExamples(
+              operation.responses[statusCode].content[contentType].schema,
+            ),
           },
         }
         responseExamples.push(example)

src/rest/scripts/utils/get-body-params.ts

@@ -20,7 +20,6 @@ export interface TransformedParam {
   name: string
   description: string
   isRequired?: boolean
-  in?: string
   childParamsGroups?: TransformedParam[]
   enum?: string[]
   oneOfObject?: boolean
@@ -31,7 +30,6 @@ interface BodyParamProps {
   paramKey?: string
   required?: string[]
   childParamsGroups?: TransformedParam[]
-  topLevel?: boolean
 }
 
 // If there is a oneOf at the top level, then we have to present just one
@@ -113,7 +111,6 @@ export async function getBodyParams(schema: Schema, topLevel = false): Promise<T
     }
     const paramDecorated = await getTransformedParam(schema, paramType, {
       required,
-      topLevel,
       childParamsGroups,
     })
     return [paramDecorated]
@@ -258,7 +255,6 @@ export async function getBodyParams(schema: Schema, topLevel = false): Promise<T
       paramKey,
       required,
       childParamsGroups,
-      topLevel,
     })
     bodyParametersParsed.push(paramDecorated)
   }
@@ -270,17 +266,14 @@ async function getTransformedParam(
   paramType: string[],
   props: BodyParamProps,
 ): Promise<TransformedParam> {
-  const { paramKey, required, childParamsGroups, topLevel } = props
+  const { paramKey, required, childParamsGroups } = props
   const paramDecorated: TransformedParam = {} as TransformedParam
   // Supports backwards compatibility for OpenAPI 3.0
   // In 3.1 a nullable type is part of the param.type array and
   // the property param.nullable does not exist.
   if (param.nullable) paramType.push('null')
   paramDecorated.type = Array.from(new Set(paramType.filter(Boolean))).join(' or ')
   paramDecorated.name = paramKey || ''
-  if (topLevel) {
-    paramDecorated.in = 'body'
-  }
   paramDecorated.description = await renderContent(param.description || '')
   if (required && required.includes(paramKey || '')) {
     paramDecorated.isRequired = true

src/rest/scripts/utils/operation.ts

@@ -64,7 +64,11 @@ export default class Operation {
     this.title = operation.summary
     this.category = operation['x-github'].category
     this.subcategory = operation['x-github'].subcategory
-    this.parameters = operation.parameters || []
+    // Shallow-clone each parameter so that renderParameterDescriptions() can
+    // safely delete fields (e.g. deprecated, example, examples) without
+    // mutating this.#operation.parameters, which renderCodeExamples() reads
+    // concurrently via getParameterExamples().
+    this.parameters = (operation.parameters || []).map((p: any) => ({ ...p }))
     this.bodyParameters = []
     return this
   }
@@ -151,6 +155,11 @@ export default class Operation {
       return Promise.all(
         this.parameters.map(async (param) => {
           param.description = await renderContent(param.description)
+          // Remove fields that are not used at runtime to keep schema.json lean
+          delete param.deprecated
+          delete param.example
+          delete param.examples
+          delete param['x-multi-segment']
           return param
         }),
       )

src/rest/tests/get-rest-code-samples.ts

@@ -35,7 +35,6 @@ describe('getGHExample - GitHub CLI code generation', () => {
     }
 
     const codeSample: CodeSample = {
-      key: 'default',
       request: {
         contentType: 'application/json',
         description: 'Example',
@@ -134,7 +133,6 @@ describe('getGHExample - GitHub CLI code generation', () => {
     }
 
     const codeSample: CodeSample = {
-      key: 'default',
       request: {
         contentType: 'application/json',
         description: 'Example',
@@ -196,7 +194,6 @@ describe('getGHExample - GitHub CLI code generation', () => {
     }
 
     const codeSample: CodeSample = {
-      key: 'default',
       request: {
         contentType: 'application/json',
         description: 'Example',