feat: Operation ID override support to transformation (#635)

Co-authored-by: Copilot <[email protected]>

Author: lovisaberggren

tools/transformer/README.md

@@ -16,7 +16,7 @@ Additionally, framework enables us to extend it by additional rules per usage to
 
 Transformations should be generic - they should be reusable across OpenAPI files and be generally an unopinionated way of
 handling OpenAPI file. That means that they would improve any public OpenAPI for.
-Parameters for transformations (actuall scripts) can be more finetuned to current OpenAPI file.
+Parameters for transformations (actual scripts) can be more finetuned to current OpenAPI file.
 
 ## Usage
 
@@ -91,10 +91,14 @@ Enums in current form are hard to ensure backwards compatibility.
 This transformation removes all openapi `nullable` fields from the schema.
 Useful for situations for schemas where nullability handling is not desired.
 
+6. Apply Operation ID Overrides
+
+This transformation updates the operation IDs in the OpenAPI file if the operation has an `x-xgen-operation-id-override` extension. Then, it removes the Operation ID override extension from the OpenAPI file.
+
 ## Transformation Validation
 
 Transformation engine does perform validation for invalid cases.
-If transformation fails it usualy means that OpenAPI file is not correct and has issues that require human attention.
+If transformation fails it usually means that OpenAPI file is not correct and has issues that require human attention.
 
 The process of fixing OpenAPI always involves:
 

tools/transformer/__tests__/input.json

@@ -34,6 +34,7 @@
       "get": {
         "description": "Info description.",
         "operationId": "versionedExample",
+        "x-xgen-operation-id-override": "getVersionedExample",
         "responses": {
           "200": {
             "content": {

tools/transformer/__tests__/transformations.test.js

@@ -4,6 +4,7 @@ const {
   applyModelNameTransformations,
   transformAllOf,
   transformOneOf,
+  applyOperationIdOverrides,
 } = require("../src/transformations");
 const cases = require("./transformations-snapshots");
 
@@ -62,3 +63,16 @@ test("applyModelNameTransformations", () => {
     expect(modelKey.endsWith("View")).toBeFalsy();
   }
 });
+
+test("applyOperationIdOverrides", () => {
+  api = applyOperationIdOverrides(api);
+  expect(
+    api.paths["/api/atlas/v1.5/groups/{groupId}/clusters"].post.operationId,
+  ).toEqual("createCluster");
+  expect(api.paths["/api/atlas/v2/example/info"].get.operationId).toEqual(
+    "getVersionedExample",
+  );
+  expect(
+    api.paths["/api/atlas/v2/example/info"].get["x-xgen-operation-id-override"],
+  ).toBeFalsy();
+});

tools/transformer/src/atlasTransformations.js

@@ -10,6 +10,7 @@ const {
   removeRefsFromParameters,
   reorderResponseBodies,
   applyFieldTransformations,
+  applyOperationIdOverrides,
 } = require("./transformations");
 const { resolveOpenAPIReference } = require("./engine/transformers");
 
@@ -71,6 +72,8 @@ module.exports = function runTransformations(openapi) {
     "#/components/parameters/pretty",
   ]);
 
+  openapi = applyOperationIdOverrides(openapi);
+
   return openapi;
 };
 

tools/transformer/src/transformations/index.js

@@ -16,6 +16,7 @@ const { applyRemoveNullableTransformations } = require("./removeNullable");
 const { removeRefsFromParameters } = require("./removeInvalidParams");
 const { reorderResponseBodies } = require("./reorderResponseBodies");
 const { applyFieldTransformations } = require("./fields");
+const { applyOperationIdOverrides } = require("./operationId");
 
 module.exports = {
   applyModelNameTransformations,
@@ -33,4 +34,5 @@ module.exports = {
   removeRefsFromParameters,
   reorderResponseBodies,
   applyFieldTransformations,
+  applyOperationIdOverrides,
 };

tools/transformer/src/transformations/operationId.js

@@ -0,0 +1,48 @@
+const OP_ID_OVERRIDE_EXTENSION = "x-xgen-operation-id-override";
+const validHttpMethods = [
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+  "trace",
+];
+
+/**
+ * Replaces Operation IDs if operation ID overrides are present and removes the
+ * override extension.
+ *
+ * @param {*} api OpenAPI JSON File
+ * @returns {*} transformed OpenAPI JSON File
+ */
+function applyOperationIdOverrides(api) {
+  const hasPaths = api && api.paths;
+  if (!hasPaths) {
+    throw new Error("Missing paths in openapi");
+  }
+
+  Object.keys(api.paths).forEach((pathKey) => {
+    const pathItem = api.paths[pathKey];
+    if (!pathItem) {
+      throw new Error("Missing path item in openapi");
+    }
+
+    validHttpMethods.forEach((method) => {
+      const operationItem = api.paths[pathKey][method];
+      if (operationItem && operationItem[OP_ID_OVERRIDE_EXTENSION]) {
+        // Update Operation ID based on override extension
+        api.paths[pathKey][method].operationId =
+          operationItem[OP_ID_OVERRIDE_EXTENSION];
+        delete api.paths[pathKey][method][OP_ID_OVERRIDE_EXTENSION];
+      }
+    });
+  });
+
+  return api;
+}
+
+module.exports = {
+  applyOperationIdOverrides,
+};