feat(respect-core): generate operationPath when operationId is missing (#1986)

Author: DmitryAnansky

.changeset/old-lamps-taste.md

@@ -0,0 +1,6 @@
+---
+"@redocly/respect-core": minor
+"@redocly/cli": minor
+---
+
+Added support for generating workflows from OpenAPI operations without operationIds. The `generate-arazzo` command now automatically generates operationPaths using the URL pattern: `{$sourceDescriptions.<name>.url}#/paths/<path>/<method>`.

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

@@ -41,8 +41,36 @@ const BUNDLED_DESCRIPTION_MOCK = {
   },
 };
 
+const BUNDLED_DESCRIPTION_MOCK_WITHOUT_OPERATION_ID = {
+  paths: {
+    '/pet': {
+      get: {
+        responses: {
+          200: {
+            description: 'OK',
+          },
+        },
+      },
+    },
+    '/fact': {
+      get: {
+        responses: {},
+      },
+    },
+  },
+  servers: [
+    {
+      url: 'https://petstore.swagger.io/v1',
+    },
+  ],
+  info: {
+    title: 'Swagger Petstore',
+    version: '1.0.0',
+  },
+};
+
 describe('generateArazzoDescription', () => {
-  it('should generate test config when output file is provided', async () => {
+  it('should generate arazzo description when output file is provided', async () => {
     (bundleOpenApi as jest.Mock).mockReturnValue(BUNDLED_DESCRIPTION_MOCK);
     expect(
       await generateArazzoDescription({
@@ -86,7 +114,7 @@ describe('generateArazzoDescription', () => {
     });
   });
 
-  it('should generate test config with', async () => {
+  it('should generate arazzo description with operationId', async () => {
     (bundleOpenApi as jest.Mock).mockReturnValue(BUNDLED_DESCRIPTION_MOCK);
     (getOperationFromDescription as jest.Mock).mockReturnValue({
       responses: {
@@ -149,7 +177,7 @@ describe('generateArazzoDescription', () => {
     });
   });
 
-  it('should generate test config with not existing description', async () => {
+  it('should generate arazzo description with not existing description', async () => {
     (bundleOpenApi as jest.Mock).mockReturnValue(undefined);
     expect(
       await generateArazzoDescription({
@@ -172,4 +200,67 @@ describe('generateArazzoDescription', () => {
       workflows: [],
     });
   });
+
+  it('should generate arazzo description with operationPath', async () => {
+    (bundleOpenApi as jest.Mock).mockReturnValue(BUNDLED_DESCRIPTION_MOCK_WITHOUT_OPERATION_ID);
+    (getOperationFromDescription as jest.Mock).mockReturnValue({
+      responses: {
+        200: {
+          description: 'OK',
+        },
+      },
+    });
+    (getRequestDataFromOpenApi as jest.Mock).mockReturnValue({
+      parameters: [
+        {
+          in: 'query',
+          name: 'limit',
+          schema: {
+            type: 'integer',
+            format: 'int32',
+          },
+        },
+      ],
+    });
+
+    expect(
+      await generateArazzoDescription({
+        descriptionPath: 'description.yaml',
+      })
+    ).toEqual({
+      arazzo: '1.0.1',
+      info: {
+        title: 'Swagger Petstore',
+        version: '1.0.0',
+      },
+      sourceDescriptions: [
+        {
+          name: 'description',
+          type: 'openapi',
+          url: 'description.yaml',
+        },
+      ],
+      workflows: [
+        {
+          workflowId: 'get-pet-workflow',
+          steps: [
+            {
+              operationPath: '{$sourceDescriptions.description.url}#/paths/~1pet/get',
+              stepId: 'get-pet-step',
+              successCriteria: [{ condition: '$statusCode == 200' }],
+            },
+          ],
+        },
+        {
+          workflowId: 'get-fact-workflow',
+          steps: [
+            {
+              operationPath: '{$sourceDescriptions.description.url}#/paths/~1fact/get',
+              stepId: 'get-fact-step',
+            },
+          ],
+        },
+      ],
+    });
+  });
 });

packages/respect-core/src/modules/arazzo-description-generator/generate-workflows-from-description.ts

@@ -64,7 +64,10 @@ export function generateWorkflowsFromDescription({
 
         const operation = descriptionPaths[pathItemKey][methodToCheck.toLowerCase() as HttpMethod];
         const operationSecurity = operation?.security || undefined;
-        const operationId = operation?.operationId || generateOperationId(pathItemKey, method);
+        const operationId = generateOperationId(sourceDescriptionName, operation?.operationId);
+        const operationPath = !operationId
+          ? generateOperationPath(sourceDescriptionName, pathItemKey, method)
+          : undefined;
         const workflowSecurityInputs = generateWorkflowSecurityInputs(
           inputsComponents,
           operationSecurity || rootSecurity || []
@@ -84,7 +87,7 @@ export function generateWorkflowsFromDescription({
           steps: [
             {
               stepId: pathKey ? `${method}-${pathKey}-step` : `${method}-step`,
-              operationId: `$sourceDescriptions.${sourceDescriptionName}.${operationId}`,
+              ...(operationId ? { operationId } : { operationPath }),
               ...generateParametersWithSuccessCriteria(
                 descriptionPaths[pathItemKey][methodToCheck.toLowerCase() as HttpMethod]?.responses
               ),
@@ -111,6 +114,21 @@ function generateParametersWithSuccessCriteria(
   return { successCriteria: [{ condition: `$statusCode == ${firstResponseCode}` }] };
 }
 
-function generateOperationId(path: string, method: OperationMethod) {
-  return `${method}@${path}`;
+function generateOperationId(sourceDescriptionName: string, operationId?: string) {
+  if (!operationId) {
+    return undefined;
+  }
+
+  return `$sourceDescriptions.${sourceDescriptionName}.${operationId}`;
+}
+
+function generateOperationPath(
+  sourceDescriptionName: string,
+  path: string,
+  method: OperationMethod
+) {
+  return `{$sourceDescriptions.${sourceDescriptionName}.url}#/paths/~1${path.replace(
+    /^\//,
+    ''
+  )}/${method}`;
 }

packages/respect-core/src/modules/description-parser/get-operation-by-id.ts

@@ -40,24 +40,15 @@ export function getOperationById(
     }
 
     for (const [method, operationDetails] of Object.entries(pathDetails)) {
-      // @ indicates autogenerated operationId
-      if (operationId.includes('@/')) {
-        // TODO: replace this with construct of path
-        const [methodPrefix, pathSuffix] = operationId.split('@');
-        if (methodPrefix === method && pathSuffix === path) {
-          return { ...operationDetails, path, method, descriptionName };
-        }
-      } else {
-        if (operationDetails.operationId === operationId) {
-          return {
-            servers: (pathDetails as any).servers || rootServers,
-            ...operationDetails,
-            pathParameters: operationDetails.parameters || [],
-            path,
-            method,
-            descriptionName,
-          };
-        }
+      if (operationDetails.operationId === operationId) {
+        return {
+          servers: (pathDetails as any).servers || rootServers,
+          ...operationDetails,
+          pathParameters: operationDetails.parameters || [],
+          path,
+          method,
+          descriptionName,
+        };
       }
     }
   }