feat: improve generate-arazzo command output (#1962)

Author: DmitryAnansky

.changeset/silver-crews-eat.md

@@ -0,0 +1,6 @@
+---
+"@redocly/respect-core": patch
+"@redocly/cli": patch
+---
+
+Added support for `basic`, `bearer`, and `apiKey` security schemes in workflow generation with `generate-arazzo` command.

packages/core/src/typings/openapi.ts

@@ -292,12 +292,12 @@ export interface Oas3SecurityRequirement {
 }
 
 export interface Oas3SecurityScheme {
-  type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
+  type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect' | 'mutualTLS';
   description?: string;
   name?: string;
   in?: 'query' | 'header' | 'cookie';
   scheme?: string;
-  bearerFormat: string;
+  bearerFormat?: string;
   flows: {
     implicit?: {
       refreshUrl?: string;

packages/respect-core/src/modules/__tests__/arazzo-description-generator/generate-inputs-arazzo-components.test.ts

@@ -0,0 +1,83 @@
+import { Oas3SecurityScheme } from 'core/src/typings/openapi';
+import { generateSecurityInputsArazzoComponents } from '../../arazzo-description-generator';
+
+describe('generateSecurityInputsArazzoComponents', () => {
+  it('should generate empty inputs for the security schemes if there are no security schemes', () => {
+    const securitySchemes = {};
+    const result = generateSecurityInputsArazzoComponents(securitySchemes);
+    expect(result).toEqual({ inputs: {} });
+  });
+
+  it('should generate the correct inputs for the Basic auth security scheme', () => {
+    const securitySchemes = {
+      basicAuth: {
+        type: 'http' as const,
+        scheme: 'basic',
+      } as Oas3SecurityScheme,
+    };
+    const result = generateSecurityInputsArazzoComponents(securitySchemes);
+    expect(result).toEqual({
+      inputs: {
+        basicAuth: {
+          type: 'object',
+          properties: {
+            basicAuth: {
+              type: 'string',
+              description: 'Basic authentication',
+              format: 'password',
+            },
+          },
+        },
+      },
+    });
+  });
+
+  it('should generate the correct inputs for the Bearer auth security scheme', () => {
+    const securitySchemes = {
+      bearerAuth: {
+        type: 'http' as const,
+        scheme: 'bearer',
+      } as Oas3SecurityScheme,
+    };
+    const result = generateSecurityInputsArazzoComponents(securitySchemes);
+    expect(result).toEqual({
+      inputs: {
+        bearerAuth: {
+          type: 'object',
+          properties: {
+            bearerAuth: {
+              type: 'string',
+              description: 'JWT Authentication token for ${name}',
+              format: 'password',
+            },
+          },
+        },
+      },
+    });
+  });
+
+  it('should generate the correct inputs for the ApiKey auth security scheme', () => {
+    const securitySchemes = {
+      apiKey: {
+        type: 'apiKey' as const,
+        name: 'X-API-Key',
+        in: 'header',
+      } as Oas3SecurityScheme,
+    };
+    const result = generateSecurityInputsArazzoComponents(securitySchemes);
+    expect(result).toEqual({
+      inputs: {
+        apiKey: {
+          type: 'object',
+          properties: {
+            apiKey: {
+              type: 'string',
+              description: 'Authentication token for apiKey',
+              format: 'password',
+            },
+          },
+        },
+      },
+    });
+  });
+});

packages/respect-core/src/modules/__tests__/arazzo-description-generator/generate-workflow-security-inputs.test.ts

@@ -0,0 +1,44 @@
+import { generateWorkflowSecurityInputs } from '../../arazzo-description-generator';
+
+describe('generateWorkflowSecurityInputs', () => {
+  it('should return undefined if there are no security requirements', () => {
+    const inputsComponents = {};
+    const security = [] as any[];
+    const result = generateWorkflowSecurityInputs(inputsComponents, security);
+    expect(result).toBeUndefined();
+  });
+
+  it('should return the correct workflow security inputs reference', () => {
+    const inputsComponents = {
+      inputs: {
+        basicAuth: {
+          type: 'object',
+        },
+        bearerAuth: {
+          type: 'string',
+        },
+      },
+    };
+    const security = [{ basicAuth: [] }];
+    const result = generateWorkflowSecurityInputs(inputsComponents, security);
+    expect(result).toEqual({
+      $ref: '#/components/inputs/basicAuth',
+    });
+  });
+
+  it('should return undefined if the security requirement is not found in the inputs components', () => {
+    const inputsComponents = {
+      inputs: {
+        basicAuth: {
+          type: 'object',
+        },
+        bearerAuth: {
+          type: 'string',
+        },
+      },
+    };
+    const security = [{ apiKey: [] }];
+    const result = generateWorkflowSecurityInputs(inputsComponents, security);
+    expect(result).toBeUndefined();
+  });
+});

packages/respect-core/src/modules/__tests__/arazzo-description-generator/generate-workflow-security-parameters.test.ts

@@ -0,0 +1,133 @@
+import { generateWorkflowSecurityParameters } from '../../arazzo-description-generator';
+
+describe('generateWorkflowSecurityParameters', () => {
+  it('should return the correct workflow security parameters for Basic authentication', () => {
+    const inputsComponents = {
+      inputs: {
+        basicAuth: {
+          type: 'object',
+          properties: {
+            basicAuth: {
+              type: 'string',
+              description: 'Basic authentication',
+              format: 'password',
+            },
+          },
+        },
+      },
+    };
+
+    const security = [{ basicAuth: [] }];
+
+    const securitySchemes = {
+      basicAuth: {
+        type: 'http',
+        scheme: 'basic',
+      },
+    } as any;
+
+    const result = generateWorkflowSecurityParameters(inputsComponents, security, securitySchemes);
+
+    expect(result).toEqual([
+      {
+        name: 'Authorization',
+        value: `Basic {$inputs.basicAuth}`,
+        in: 'header',
+      },
+    ]);
+  });
+
+  it('should return the correct workflow security parameters for Bearer authentication', () => {
+    const inputsComponents = {
+      inputs: {
+        bearerAuth: {
+          type: 'string',
+          description: 'Bearer token',
+          format: 'password',
+        },
+      },
+    };
+
+    const security = [{ bearerAuth: [] }];
+
+    const securitySchemes = {
+      bearerAuth: {
+        type: 'http',
+        scheme: 'bearer',
+      },
+    } as any;
+
+    const result = generateWorkflowSecurityParameters(inputsComponents, security, securitySchemes);
+
+    expect(result).toEqual([
+      {
+        name: 'Authorization',
+        value: `Bearer {$inputs.bearerAuth}`,
+        in: 'header',
+      },
+    ]);
+  });
+
+  it('should return the correct workflow security parameters for ApiKey authentication', () => {
+    const inputsComponents = {
+      inputs: {
+        apiKey: {
+          type: 'string',
+          description: 'ApiKey token',
+          format: 'password',
+        },
+      },
+    };
+
+    const security = [{ apiKey: [] }];
+
+    const securitySchemes = {
+      apiKey: {
+        type: 'apiKey',
+        name: 'X-API-Key',
+        in: 'header',
+      },
+    } as any;
+
+    const result = generateWorkflowSecurityParameters(inputsComponents, security, securitySchemes);
+
+    expect(result).toEqual([
+      {
+        name: 'X-API-Key',
+        value: `$inputs.apiKey`,
+        in: 'header',
+      },
+    ]);
+  });
+
+  it('should return an empty array if there are no security parameters', () => {
+    const inputsComponents = {};
+    const security = [] as any;
+    const securitySchemes = {};
+
+    const result = generateWorkflowSecurityParameters(inputsComponents, security, securitySchemes);
+
+    expect(result).toEqual([]);
+  });
+
+  it('should return an empty array if the security scheme is not supported', () => {
+    const inputsComponents = {
+      inputs: {
+        oauth2Auth: {
+          type: 'string',
+          description: 'OAuth2 token',
+        },
+      },
+    };
+    const security = [{ oauth2Auth: [] }] as any;
+    const securitySchemes = {
+      oauth2Auth: {
+        type: 'oauth2',
+      },
+    } as any;
+
+    const result = generateWorkflowSecurityParameters(inputsComponents, security, securitySchemes);
+
+    expect(result).toEqual([]);
+  });
+});