oas-toolkit 0.8.0 → 0.10.0

package/README.md

@@ -34,3 +34,21 @@ Merge the following lists/objects recursively. If you encounter a list, concaten
 - tags
 - components
 - paths
+
+## Remove by Annotation
+
+```bash
+oas-toolkit remove-with-annotation --annotation x-visibility.internal=true /tmp/openapi.yaml
+```
+
+Remove paths or operations from an OpenAPI spec based on an annotation. The example provided will remove any paths or operations with the following annotation:
+
+```json
+{
+  "x-visibility": {
+    "internal": true
+  }
+}
+```
+
+You can pass `--remove-unused` to run `remove-unused-components` and `remove-tags` after running this command.

package/canonical-server.js

@@ -0,0 +1,47 @@
+const isEqual = require("lodash.isequal");
+const uniqWith = require("lodash.uniqwith");
+const url = require("url");
+function run(oas) {
+  oas = JSON.parse(JSON.stringify(oas)); // Prevent modification of original object
+
+  // Extract the base path from servers
+  const basePaths = uniqWith(
+    oas.servers.map((server) => {
+      const path = url.parse(server.url).pathname;
+      if (path.slice(-1) === "/") {
+        return path.slice(0, -1);
+      }
+      return path;
+    }),
+    isEqual
+  );
+
+  if (basePaths.length > 1) {
+    throw new Error(
+      `Base paths are different in the servers block. Found: ${basePaths.join(
+        ", "
+      )}`
+    );
+  }
+
+  for (let path in oas.paths) {
+    let newPath = basePaths[0] + path;
+    oas.paths[newPath] = oas.paths[path];
+    delete oas.paths[path];
+  }
+
+  // Remove paths from servers
+  oas.servers = oas.servers.map((server) => {
+    const u = url.parse(server.url);
+    return {
+      ...server,
+      url: `${u.protocol}//${u.hostname}/`,
+    };
+  });
+
+  return oas;
+}
+
+module.exports = {
+  run,
+};

package/canonical-server.test.js

@@ -0,0 +1,77 @@
+const c = require("./canonical-server");
+
+const oas = {
+  servers: [
+    {
+      url: "https://api.example.com/v1",
+    },
+  ],
+  paths: {
+    "/foo/hello": {},
+    "/foo/world": {},
+  },
+};
+
+function getOas(urls) {
+  return {
+    servers: urls.map((url) => {
+      return {
+        url,
+      };
+    }),
+    paths: oas.paths,
+  };
+}
+
+describe("#run", () => {
+  it("prefixes all routes", () => {
+    const o = getOas(["https://api.example.com/v1"]);
+    expect(c.run(o).paths).toEqual({
+      "/v1/foo/hello": {},
+      "/v1/foo/world": {},
+    });
+  });
+
+  it("handles multiple servers", () => {
+    const o = getOas([
+      "https://api.example.com/v1",
+      "https://stagingapi.example.com/v1",
+    ]);
+    expect(c.run(o).paths).toEqual({
+      "/v1/foo/hello": {},
+      "/v1/foo/world": {},
+    });
+  });
+
+  it("handles trailing slashes", () => {
+    const o = getOas([
+      "https://api.example.com/v1/",
+      "https://stagingapi.example.com/v1/",
+    ]);
+    expect(c.run(o).paths).toEqual({
+      "/v1/foo/hello": {},
+      "/v1/foo/world": {},
+    });
+  });
+
+  it("throws if the paths are different in a single OAS", () => {
+    const o = getOas([
+      "https://api.example.com/v1",
+      "https://api.example.com/v2",
+    ]);
+    expect(() => c.run(o).paths).toThrow(
+      "Base paths are different in the servers block. Found: /v1, /v2"
+    );
+  });
+
+  it("rewrites the servers", () => {
+    const o = getOas([
+      "https://api.example.com/v1",
+      "https://stagingapi.example.com/v1",
+    ]);
+    expect(c.run(o).servers).toEqual([
+      { url: "https://api.example.com/" },
+      { url: "https://stagingapi.example.com/" },
+    ]);
+  });
+});

package/cli/bin.js

@@ -5,25 +5,44 @@ const { hideBin } = require("yargs/helpers");
 
 yargs(hideBin(process.argv))
   .command(
-    "merge <openapi.yaml> <...more.yaml>",
+    "merge <openapi> <...more.yaml>",
     "merge the provided OpenAPI files",
     require("./commands/merge")
   )
   .command(
-    "check-conflicts <openapi.yaml> <...more.yaml>",
+    "check-conflicts <openapi> <...more.yaml>",
     "check for conflicting components, paths, tags, and security schemes",
     require("./commands/check-conflicts")
   )
   .command(
-    "remove-unused-components <openapi.yaml>",
+    "remove-unused-components <openapi>",
     "remove unused components from the provided OpenAPI file",
     require("./commands/remove-unused-components")
   )
   .command(
-    "remove-unused-tags <openapi.yaml>",
+    "remove-unused-tags <openapi>",
     "remove unused tags from the provided OpenAPI file",
     require("./commands/remove-unused-tags")
   )
+  .command(
+    "remove-with-annotation <openapi>",
+    "remove all paths/select paths/operations with a specific annotation from the provided OpenAPI file",
+    (yargs) => {
+      yargs.option("annotation", {
+        demandOption: true,
+      });
+      yargs.option("remove-unused", {
+        demandOption: false,
+        type: "boolean",
+      });
+      yargs.positional("openapi", {
+        require: true,
+        describe: "the OpenAPI file to rewrite",
+        type: "string",
+      });
+    },
+    require("./commands/remove-with-annotation")
+  )
   .command(
     "rewrite-path <openapi>",
     "rewrite paths in the provided OpenAPI file",
@@ -42,4 +61,16 @@ yargs(hideBin(process.argv))
     },
     require("./commands/rewrite-path")
   )
+  .command(
+    "canonical-server <openapi>",
+    "move the path from the servers block in to /paths",
+    (yargs) => {
+      yargs.positional("openapi", {
+        require: true,
+        describe: "the OpenAPI file to rewrite",
+        type: "string",
+      });
+    },
+    require("./commands/canonical-server")
+  )
   .parse();

package/cli/commands/canonical-server.js

@@ -0,0 +1,14 @@
+const fs = require("fs");
+const yaml = require("js-yaml");
+
+module.exports = async function (argv) {
+  try {
+    const p = require("../../canonical-server");
+    let oas = yaml.load(fs.readFileSync(argv.openapi));
+    oas = p.run(oas);
+    console.log(yaml.dump(oas));
+  } catch (e) {
+    console.error(`ERROR: ${e.message}`);
+    process.exit(1);
+  }
+};

package/cli/commands/remove-with-annotation.js

@@ -0,0 +1,22 @@
+const fs = require("fs");
+const yaml = require("js-yaml");
+const { removeUnusedComponents } = require("../../components");
+const { removeUnusedTags } = require("../../tags");
+
+module.exports = async function (argv) {
+  try {
+    const p = require("../../remove-with-annotation");
+    let oas = yaml.load(fs.readFileSync(argv.openapi));
+    oas = p.remove(oas, argv.annotation);
+
+    if (argv["remove-unused"]) {
+      oas = removeUnusedComponents(oas);
+      oas = removeUnusedTags(oas);
+    }
+
+    console.log(yaml.dump(oas));
+  } catch (e) {
+    console.error(`ERROR: ${e.message}`);
+    process.exit(1);
+  }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oas-toolkit",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "",
   "main": "index.js",
   "bin": {

package/remove-with-annotation.js

@@ -0,0 +1,43 @@
+const get = require("lodash.get");
+function remove(oas, annotation) {
+  oas = JSON.parse(JSON.stringify(oas)); // Prevent modification of original object
+  let [key, value] = annotation.split("=");
+
+  // Coerce booleans in value
+  if (value === "true") {
+    value = true;
+  }
+  if (value === "false") {
+    value = false;
+  }
+
+  // Remove at a global level
+  if (get(oas, key) === value) {
+    delete oas.paths;
+  }
+
+  // Remove at an operation level
+  for (let operation in oas.paths) {
+    if (get(oas.paths[operation], key) === value) {
+      delete oas.paths[operation];
+    }
+
+    // Remove at a path level
+    for (let path in oas.paths[operation]) {
+      if (get(oas.paths[operation][path], key) === value) {
+        delete oas.paths[operation][path];
+      }
+
+      // If the operation is now empty, remove it
+      if (Object.keys(oas.paths[operation]).length === 0) {
+        delete oas.paths[operation];
+      }
+    }
+  }
+
+  return oas;
+}
+
+module.exports = {
+  remove,
+};

package/remove-with-annotation.test.js

@@ -0,0 +1,118 @@
+const p = require("./remove-with-annotation");
+
+const hello = {
+  post: {
+    operationId: "create-hello",
+    requestBody: {
+      $ref: "#/components/requestBodies/CreateHello",
+    },
+    responses: {},
+  },
+  get: {
+    operationId: "get-hello",
+    responses: {},
+  },
+};
+
+const world = {
+  get: {
+    operationId: "create-world",
+    requestBody: {
+      $ref: "#/components/requestBodies/CreateWorld",
+    },
+    responses: {},
+  },
+};
+
+const oas = {
+  paths: {
+    "/v1/foo/hello": hello,
+    "/v1/foo/world": world,
+  },
+};
+
+describe("#remove-with-annotation", () => {
+  describe("global", () => {
+    it("removes a scalar global item", () => {
+      const testOas = {
+        "x-visibility": "internal",
+        ...oas,
+      };
+      expect(p.remove(testOas, "x-visibility=internal")).toEqual({
+        "x-visibility": "internal",
+      });
+    });
+
+    it("removes a boolean global item", () => {
+      const testOas = {
+        "x-hidden": true,
+        ...oas,
+      };
+      expect(p.remove(testOas, "x-hidden=true")).toEqual({
+        "x-hidden": true,
+      });
+    });
+
+    it("removes a nested global item", () => {
+      const testOas = {
+        "x-visibility": {
+          publish: "INTERNAL",
+        },
+        ...oas,
+      };
+      expect(p.remove(testOas, "x-visibility.publish=INTERNAL")).toEqual({
+        "x-visibility": {
+          publish: "INTERNAL",
+        },
+      });
+    });
+  });
+
+  describe("operation", () => {
+    it("removes a nested operation item", () => {
+      const testOas = {
+        paths: {
+          "/v1/foo/hello": {
+            "x-visibility": {
+              publish: "INTERNAL",
+            },
+            ...hello,
+          },
+          "/v1/foo/world": world,
+        },
+      };
+      expect(p.remove(testOas, "x-visibility.publish=INTERNAL")).toEqual({
+        paths: {
+          "/v1/foo/world": world,
+        },
+      });
+    });
+  });
+
+  describe("path", () => {
+    it("removes a nested path item", () => {
+      const testOas = {
+        paths: {
+          "/v1/foo/hello": {
+            get: {
+              "x-visibility": {
+                publish: "INTERNAL",
+              },
+              ...hello.get,
+            },
+            post: hello.post,
+          },
+          "/v1/foo/world": world,
+        },
+      };
+      expect(p.remove(testOas, "x-visibility.publish=INTERNAL")).toEqual({
+        paths: {
+          "/v1/foo/hello": {
+            post: hello.post,
+          },
+          "/v1/foo/world": world,
+        },
+      });
+    });
+  });
+});