fix(oas): render reserved Authorization header param when operation has no security scheme (CX-3611)

Author: gkoberger

.changeset/cx-3611-authorization-header-param.md

@@ -0,0 +1,5 @@
+---
+"oas": patch
+---
+
+`getParametersAsJSONSchema()` no longer strips a custom `Authorization` header parameter when the operation has no applicable security scheme. `Accept` and `Content-Type` remain reserved (ReadMe computes them), but `Authorization` is only ignored when a security scheme already provides an auth affordance — otherwise dropping it silently removed the only way to authenticate the request (CX-3611).

packages/oas/src/operation/transformers/get-parameters-as-json-schema.ts

@@ -17,10 +17,25 @@ import {
 } from '../../lib/refs.js';
 import { isRef } from '../../types.js';
 
-const RESERVED_HEADER_PARAMETERS = new Set(['accept', 'authorization', 'content-type']);
+// `Accept` and `Content-Type` are always reserved: ReadMe computes them from the operation's
+// response media types and request body, so rendering them as editable header params is redundant
+// and can interfere with request body serialization.
+const RESERVED_HEADER_PARAMETERS = new Set(['accept', 'content-type']);
 
-function isReservedHeaderParameter(param: ParameterObject) {
-  return param.in === 'header' && RESERVED_HEADER_PARAMETERS.has(param.name.toLowerCase());
+/**
+ * `Authorization` is also reserved by the OpenAPI spec, but unlike `Accept`/`Content-Type` nothing
+ * auto-computes it — it's only ever supplied when the operation has a security scheme. So we only
+ * treat a custom `Authorization` header param as reserved when the operation actually has security
+ * requirements; otherwise stripping it would remove the only affordance to authenticate the
+ * request, silently breaking docs that model auth this way (CX-3611).
+ */
+function isReservedHeaderParameter(param: ParameterObject, hasSecurity: boolean) {
+  if (param.in !== 'header') return false;
+
+  const name = param.name.toLowerCase();
+  if (RESERVED_HEADER_PARAMETERS.has(name)) return true;
+
+  return hasSecurity && name === 'authorization';
 }
 
 /**
@@ -176,13 +191,14 @@ export function getParametersAsJSONSchema(
 
   function transformParameters(): SchemaWrapper[] {
     const operationParams = operation.getParameters();
+    const hasSecurity = operation.getSecurity().length > 0;
 
     const transformed = Object.keys(types)
       .map(type => {
         const required: string[] = [];
 
         const parameters = operationParams.filter(param => {
-          return param.in === type && !isReservedHeaderParameter(param);
+          return param.in === type && !isReservedHeaderParameter(param, hasSecurity);
         });
         if (parameters.length === 0) {
           return null;

packages/oas/test/operation/transformers/get-parameters-as-json-schema.test.ts

@@ -79,17 +79,55 @@ describe('.getParametersAsJSONSchema()', () => {
   });
 
   it('should ignore reserved custom header parameters case-insensitively', async () => {
+    const oas = createOasForOperation(
+      {
+        security: [{ bearerAuth: [] }],
+        parameters: [
+          { in: 'header', name: 'Accept', required: true, schema: { type: 'string' } },
+          { in: 'header', name: 'accept', required: true, schema: { type: 'string' } },
+          { in: 'header', name: 'ACCEPT', required: true, schema: { type: 'string' } },
+          { in: 'header', name: 'Content-Type', required: true, schema: { type: 'string' } },
+          { in: 'header', name: 'content-type', required: true, schema: { type: 'string' } },
+          { in: 'header', name: 'CONTENT-TYPE', required: true, schema: { type: 'string' } },
+          { in: 'header', name: 'Authorization', required: true, schema: { type: 'string' } },
+          { in: 'header', name: 'authorization', required: true, schema: { type: 'string' } },
+          { in: 'header', name: 'AUTHORIZATION', required: true, schema: { type: 'string' } },
+          { in: 'header', name: 'X-Request-ID', required: true, schema: { type: 'string' } },
+        ],
+      },
+      { securitySchemes: { bearerAuth: { type: 'http', scheme: 'bearer' } } },
+    );
+
+    const schemas = oas.operation('/', 'get').getParametersAsJSONSchema();
+
+    expect(schemas).toStrictEqual([
+      {
+        label: 'Headers',
+        type: 'header',
+        schema: {
+          $schema: 'http://json-schema.org/draft-04/schema#',
+          type: 'object',
+          properties: {
+            'X-Request-ID': {
+              type: 'string',
+            },
+          },
+          required: ['X-Request-ID'],
+        },
+      },
+    ]);
+    await expect(schemas?.map(s => s.schema)).toBeValidJSONSchemas();
+  });
+
+  it('should render a reserved `Authorization` header param when the operation has no security scheme (CX-3611)', async () => {
+    // `Accept` and `Content-Type` are still ignored because ReadMe computes them, but stripping
+    // `Authorization` here would remove the only way to authenticate, so it should render.
     const oas = createOasForOperation({
       parameters: [
         { in: 'header', name: 'Accept', required: true, schema: { type: 'string' } },
-        { in: 'header', name: 'accept', required: true, schema: { type: 'string' } },
-        { in: 'header', name: 'ACCEPT', required: true, schema: { type: 'string' } },
         { in: 'header', name: 'Content-Type', required: true, schema: { type: 'string' } },
-        { in: 'header', name: 'content-type', required: true, schema: { type: 'string' } },
-        { in: 'header', name: 'CONTENT-TYPE', required: true, schema: { type: 'string' } },
         { in: 'header', name: 'Authorization', required: true, schema: { type: 'string' } },
         { in: 'header', name: 'authorization', required: true, schema: { type: 'string' } },
-        { in: 'header', name: 'AUTHORIZATION', required: true, schema: { type: 'string' } },
         { in: 'header', name: 'X-Request-ID', required: true, schema: { type: 'string' } },
       ],
     });
@@ -104,11 +142,17 @@ describe('.getParametersAsJSONSchema()', () => {
           $schema: 'http://json-schema.org/draft-04/schema#',
           type: 'object',
           properties: {
+            Authorization: {
+              type: 'string',
+            },
+            authorization: {
+              type: 'string',
+            },
             'X-Request-ID': {
               type: 'string',
             },
           },
-          required: ['X-Request-ID'],
+          required: ['Authorization', 'authorization', 'X-Request-ID'],
         },
       },
     ]);