Add x-prefix and x-placeholder for OpenAPI security scheme

Author: nolannbiron

packages/openapi-parser/src/types.ts

@@ -75,6 +75,15 @@ export interface OpenAPICustomOperationProperties {
  */
 export interface OpenAPICustomPrefillProperties {
     'x-gitbook-prefill'?: string;
+    /**
+     * Placeholder to override the default one for the security scheme.
+     */
+    'x-placeholder'?: string;
+    /**
+     * Prefix to override the default one for the security scheme (e.g., "Bearer", "Basic", "Token").
+     * Used in Authorization headers for HTTP and OAuth2 security schemes.
+     */
+    'x-prefix'?: string;
 }
 
 export type OpenAPIStability = 'experimental' | 'alpha' | 'beta';

packages/react-openapi/src/OpenAPICodeSample.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'bun:test';
+import { getSecurityHeaders } from './OpenAPICodeSample';
+import type { OpenAPIOperationData } from './types';
+
+describe('getSecurityHeaders', () => {
+    it('should handle custom HTTP scheme with x-prefix', () => {
+        const securities: OpenAPIOperationData['securities'] = [
+            [
+                'customScheme',
+                {
+                    type: 'apiKey',
+                    in: 'header',
+                    name: 'Authorization',
+                    'x-prefix': 'CustomScheme',
+                },
+            ],
+        ];
+
+        const result = getSecurityHeaders({
+            securityRequirement: [{ customScheme: [] }],
+            securities,
+        });
+
+        expect(result).toEqual({
+            Authorization: 'CustomScheme YOUR_SECRET_TOKEN',
+        });
+    });
+
+    it('should use x-prefix with x-placeholder together', () => {
+        const securities: OpenAPIOperationData['securities'] = [
+            [
+                'customAuth',
+                {
+                    type: 'apiKey',
+                    in: 'header',
+                    name: 'Authorization',
+                    'x-prefix': 'Token',
+                    'x-placeholder': 'MY_CUSTOM_TOKEN',
+                },
+            ],
+        ];
+
+        const result = getSecurityHeaders({
+            securityRequirement: [{ customAuth: [] }],
+            securities,
+        });
+
+        expect(result).toEqual({
+            Authorization: 'Token MY_CUSTOM_TOKEN',
+        });
+    });
+});

packages/react-openapi/src/OpenAPICodeSample.tsx

@@ -290,7 +290,7 @@ function getCustomCodeSamples(props: {
     return customCodeSamples;
 }
 
-function getSecurityHeaders(args: {
+export function getSecurityHeaders(args: {
     securityRequirement: OpenAPIV3.OperationObject['security'];
     securities: OpenAPIOperationData['securities'];
 }): {
@@ -314,7 +314,7 @@ function getSecurityHeaders(args: {
     for (const security of selectedSecurity.schemes) {
         switch (security.type) {
             case 'http': {
-                let scheme = security.scheme;
+                const scheme = security.scheme;
                 const defaultPlaceholderValue = scheme?.toLowerCase()?.includes('basic')
                     ? 'username:password'
                     : 'YOUR_SECRET_TOKEN';
@@ -323,15 +323,21 @@ function getSecurityHeaders(args: {
                     defaultPlaceholderValue,
                 });
 
-                if (scheme?.includes('bearer')) {
-                    scheme = 'Bearer';
-                } else if (scheme?.includes('basic')) {
-                    scheme = 'Basic';
-                } else if (scheme?.includes('token')) {
-                    scheme = 'Token';
+                // Use x-prefix if provided, otherwise fall back to default logic
+                let prefix = security['x-prefix'];
+                if (!prefix) {
+                    if (scheme?.includes('bearer')) {
+                        prefix = 'Bearer';
+                    } else if (scheme?.includes('basic')) {
+                        prefix = 'Basic';
+                    } else if (scheme?.includes('token')) {
+                        prefix = 'Token';
+                    } else {
+                        prefix = scheme ?? '';
+                    }
                 }
 
-                headers.Authorization = `${scheme} ${format}`;
+                headers.Authorization = `${prefix} ${format}`;
                 break;
             }
             case 'apiKey': {
@@ -346,10 +352,13 @@ function getSecurityHeaders(args: {
                 break;
             }
             case 'oauth2': {
-                headers.Authorization = `Bearer ${resolvePrefillCodePlaceholderFromSecurityScheme({
-                    security: security,
-                    defaultPlaceholderValue: 'YOUR_OAUTH2_TOKEN',
-                })}`;
+                const prefix = security['x-prefix'] ?? 'Bearer';
+                headers.Authorization = `${prefix} ${resolvePrefillCodePlaceholderFromSecurityScheme(
+                    {
+                        security: security,
+                        defaultPlaceholderValue: 'YOUR_OAUTH2_TOKEN',
+                    }
+                )}`;
                 break;
             }
             default: {

packages/react-openapi/src/util/tryit-prefill.test.ts

@@ -415,6 +415,70 @@ describe('resolvePrefillCodePlaceholderFromSecurityScheme (integration style)',
 
         expect(result).toBe('');
     });
+
+    it('should return x-placeholder when x-gitbook-prefill is not present', () => {
+        const result = resolvePrefillCodePlaceholderFromSecurityScheme({
+            security: {
+                type: 'apiKey',
+                in: 'header',
+                name: 'Authorization',
+                'x-placeholder': 'API_TOKEN_KEY',
+            },
+        });
+
+        expect(result).toBe('API_TOKEN_KEY');
+    });
+
+    it('should use x-placeholder with defaultPlaceholderValue fallback', () => {
+        const result = resolvePrefillCodePlaceholderFromSecurityScheme({
+            security: {
+                type: 'http',
+                scheme: 'bearer',
+                'x-placeholder': 'MY_CUSTOM_TOKEN',
+            },
+            defaultPlaceholderValue: 'YOUR_API_TOKEN',
+        });
+
+        expect(result).toBe('MY_CUSTOM_TOKEN');
+    });
+
+    it('should prioritize x-gitbook-prefill over x-placeholder when both are present', () => {
+        const result = resolvePrefillCodePlaceholderFromSecurityScheme({
+            security: {
+                type: 'http',
+                scheme: 'bearer',
+                'x-gitbook-prefill': '{{ visitor.claims.apiToken }}',
+                'x-placeholder': 'API_TOKEN_KEY',
+            },
+        });
+
+        expect(result).toBe('$$__X-GITBOOK-PREFILL[(visitor.claims.apiToken)]__$$');
+    });
+
+    it('should return x-placeholder for apiKey scheme', () => {
+        const result = resolvePrefillCodePlaceholderFromSecurityScheme({
+            security: {
+                type: 'apiKey',
+                in: 'header',
+                name: 'X-API-KEY',
+                'x-placeholder': 'YOUR_API_KEY_HERE',
+            },
+        });
+
+        expect(result).toBe('YOUR_API_KEY_HERE');
+    });
+
+    it('should return x-placeholder for basic auth scheme', () => {
+        const result = resolvePrefillCodePlaceholderFromSecurityScheme({
+            security: {
+                type: 'http',
+                scheme: 'basic',
+                'x-placeholder': 'username:password',
+            },
+        });
+
+        expect(result).toBe('username:password');
+    });
 });
 
 describe('resolveURLWithPrefillCodePlaceholdersFromServer', () => {

packages/react-openapi/src/util/tryit-prefill.ts

@@ -177,6 +177,10 @@ export function resolvePrefillCodePlaceholderFromSecurityScheme(args: {
     const prefillExprParts = extractPrefillExpressionPartsFromSecurityScheme(security);
 
     if (prefillExprParts.length === 0) {
+        // If no x-gitbook-prefill, check for x-placeholder
+        if (security['x-placeholder']) {
+            return security['x-placeholder'];
+        }
         return defaultPlaceholderValue ?? '';
     }
     const prefillExpr = templatePartsToExpression(prefillExprParts);