feat: enhance oapiRef function with options for deep extraction and property filtering

Author: radist2s

packages/openapi-plugin/src/lib/QraftCommand.ts

@@ -71,6 +71,10 @@ export class QraftCommand extends QraftCommandBase<OpenAPIQraftCommandActionOpti
         'Use OpenAPI Operation `endpoint[<index>]` path part (e.g.: "/0/1/2") or `tags` as the base name of the service.',
         'endpoint[0]'
       )
+      .option(
+        '--root-security',
+        'Use root-level OpenAPI security as the default for operations without their own security. Operation-level security overrides it according to OpenAPI semantics.'
+      )
       .addOption(createRedoclyOption());
   }
 
@@ -147,6 +151,7 @@ export class QraftCommand extends QraftCommandBase<OpenAPIQraftCommandActionOpti
     let services = getServices(schema as OpenAPISchemaType, {
       postfixServices: args.postfixServices,
       serviceNameBase: args.serviceNameBase,
+      rootSecurity: args.rootSecurity,
     });
 
     if (args.operationNameModifier) {

packages/openapi-plugin/src/lib/open-api/OpenAPISchemaType.ts

@@ -4,6 +4,7 @@ export type OpenAPISchemaType = {
     title: string;
     version: string;
   };
+  security?: Array<Record<string, string[] | undefined>>;
   paths: {
     [path: string]: {
       [method: string]: {
@@ -23,7 +24,7 @@ export type OpenAPISchemaType = {
           required?: boolean;
         };
         responses: {
-          [statusCode in number | 'default']: {
+          [statusCode in number | 'default']?: {
             $ref?: string;
             description?: string;
             content?: {

packages/openapi-plugin/src/lib/open-api/getServices.spec.ts

@@ -1,3 +1,4 @@
+import type { OpenAPISchemaType } from './OpenAPISchemaType.js';
 import openAPI from '@openapi-qraft/test-fixtures/openapi.json' with { type: 'json' };
 import { describe, expect, it } from 'vitest';
 import { filterDocumentPaths } from '../filterDocumentPaths.js';
@@ -31,4 +32,126 @@ describe('getServices', () => {
   it('matches snapshot with "serviceNameBase: tags"', () => {
     expect(getServices(openAPI, { serviceNameBase: 'tags' })).toMatchSnapshot();
   });
+
+  it('inherits root-level security when `rootSecurity` is enabled and operation-level security is omitted', () => {
+    const document: OpenAPISchemaType = {
+      openapi: '3.1.0',
+      info: {
+        title: 'Fixture API',
+        version: '1.0.0',
+      },
+      security: [{ jwtUserToken: [] }],
+      paths: {
+        '/accounts': {
+          get: {
+            operationId: 'getAccounts',
+            responses: {
+              200: {
+                description: 'Successful response',
+              },
+            },
+          },
+        },
+      },
+      components: {
+        parameters: undefined,
+      },
+    };
+
+    expect(
+      getServices(document, { rootSecurity: true })[0]?.operations[0]?.security
+    ).toEqual([{ jwtUserToken: [] }]);
+  });
+
+  it('does not inherit root-level security when `rootSecurity` is disabled', () => {
+    const document: OpenAPISchemaType = {
+      openapi: '3.1.0',
+      info: {
+        title: 'Fixture API',
+        version: '1.0.0',
+      },
+      security: [{ jwtUserToken: [] }],
+      paths: {
+        '/accounts': {
+          get: {
+            operationId: 'getAccounts',
+            responses: {
+              200: {
+                description: 'Successful response',
+              },
+            },
+          },
+        },
+      },
+      components: {
+        parameters: undefined,
+      },
+    };
+
+    expect(
+      getServices(document, { rootSecurity: false })[0]?.operations[0]?.security
+    ).toBeUndefined();
+  });
+
+  it('prefers operation-level security over root-level security when `rootSecurity` is enabled', () => {
+    const document: OpenAPISchemaType = {
+      openapi: '3.1.0',
+      info: {
+        title: 'Fixture API',
+        version: '1.0.0',
+      },
+      security: [{ jwtUserToken: [] }],
+      paths: {
+        '/accounts': {
+          get: {
+            operationId: 'getAccounts',
+            security: [{ apiKey: [] }],
+            responses: {
+              200: {
+                description: 'Successful response',
+              },
+            },
+          },
+        },
+      },
+      components: {
+        parameters: undefined,
+      },
+    };
+
+    expect(
+      getServices(document, { rootSecurity: true })[0]?.operations[0]?.security
+    ).toEqual([{ apiKey: [] }]);
+  });
+
+  it('treats empty operation-level security as an explicit override when `rootSecurity` is enabled', () => {
+    const document: OpenAPISchemaType = {
+      openapi: '3.1.0',
+      info: {
+        title: 'Fixture API',
+        version: '1.0.0',
+      },
+      security: [{ jwtUserToken: [] }],
+      paths: {
+        '/health': {
+          get: {
+            operationId: 'getHealth',
+            security: [],
+            responses: {
+              200: {
+                description: 'Successful response',
+              },
+            },
+          },
+        },
+      },
+      components: {
+        parameters: undefined,
+      },
+    };
+
+    expect(
+      getServices(document, { rootSecurity: true })[0]?.operations[0]?.security
+    ).toEqual([]);
+  });
 });

packages/openapi-plugin/src/lib/open-api/getServices.ts

@@ -29,13 +29,15 @@ export type ServiceOperation = ServiceOperationStable;
 export interface ServiceOutputOptions {
   postfixServices?: string; // todo::rename to `postfixService`
   serviceNameBase?: ServiceBaseName;
+  rootSecurity?: boolean;
 }
 
 export const getServices = (
   openApiJson: OpenAPISchemaType,
   {
     postfixServices = 'Service',
     serviceNameBase = 'endpoint[0]',
+    rootSecurity,
   }: ServiceOutputOptions = {}
 ) => {
   const paths = openApiJson.paths;
@@ -56,6 +58,11 @@ export const getServices = (
       }
 
       const methodOperation = paths[path][method];
+      const operationSecurity = resolveOperationSecurity(
+        openApiJson.security,
+        methodOperation,
+        rootSecurity
+      );
 
       const { success, errors } = Object.entries(
         methodOperation.responses
@@ -66,6 +73,8 @@ export const getServices = (
         >
       >(
         (acc, [statusCode, response]) => {
+          if (!response) return acc;
+
           if (response.$ref) {
             response = resolveDocumentLocalRef(
               response.$ref,
@@ -145,7 +154,7 @@ export const getServices = (
                 )
               : methodOperation.requestBody) ?? undefined,
           success: success,
-          security: methodOperation.security,
+          security: operationSecurity,
         });
       }
     }
@@ -154,6 +163,18 @@ export const getServices = (
   return Array.from(services.values());
 };
 
+const resolveOperationSecurity = (
+  rootSecurity: OpenAPISchemaType['security'],
+  methodOperation: OpenAPISchemaType['paths'][string][string],
+  shouldUseRootSecurity?: boolean
+) => {
+  if (shouldUseRootSecurity && !('security' in methodOperation)) {
+    return rootSecurity;
+  }
+
+  return methodOperation.security;
+};
+
 export const supportedMethod = (
   method: unknown
 ): method is (typeof supportedHTTPMethods)[number] =>