oas-toolkit 0.1.0

package/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [16.x, 18.x, 20.x]
+
+    env:
+      CI: true
+    steps:
+      - uses: actions/checkout@v3
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm ci
+      - run: npm test

package/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: NPM Publish
+
+permissions:
+  contents: write
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        ref: ${{ github.event.release.target_commitish }}
+    - name: Use Node.js 18
+      uses: actions/setup-node@v3
+      with:
+        node-version: 18
+        registry-url: https://registry.npmjs.org/
+    - run: npm ci
+    - run: git config --global user.name "Michael Heap"
+    - run: git config --global user.email "m@michaelheap.com"
+    - run: npm version ${{ github.event.release.tag_name }}
+    - run: npm run build --if-present
+    - run: npm test --if-present
+    - run: npm publish
+      env:
+        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+    - run: git push
+      env:
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+    - run: git tag -f ${{ github.event.release.tag_name }} ${{ github.event.release.target_commitish }}
+      env:
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+    - run: git push origin ${{ github.event.release.tag_name }} --force
+      env:
+        github-token: ${{ secrets.GITHUB_TOKEN }}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License Copyright (c) 2023 Michael Heap
+
+Permission is hereby granted, free
+of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice
+(including the next paragraph) shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+## oas-toolkit
+
+`oas-toolkit` is a library and CLI for working with OpenAPI documents.
+
+> The CLI only supports YAML OpenAPI specifications currently
+
+The project provides the following functionality:
+
+- Merge multiple OAS documents into a single file
+- Add/patch values in place
+- Remove arbritary keys from the specification
+- Remove unused components
+
+## Merge
+
+Usage:
+
+```bash
+oas-toolkit merge <one> <two> <three> > openapi.yml
+```
+
+Combining multiple OpenAPI specs has unspecified behaviour. This tool merges using the following algorithm:
+
+Take the latest specified value for the following blocks:
+
+- openapi
+- info
+- servers
+- externalDocs
+
+Merge the following lists/objects recursively. If you encounter a list, concatenate them together:
+
+- security
+- tags
+- components
+- paths

package/cli/bin.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+const yargs = require("yargs/yargs");
+const { hideBin } = require("yargs/helpers");
+
+yargs(hideBin(process.argv))
+  .command(
+    "merge <openapi.yaml> <...more.yaml>",
+    "merge the provided OpenAPI files",
+    require("./commands/merge")
+  )
+  .parse();

package/cli/commands/merge.js

@@ -0,0 +1,24 @@
+const fs = require("fs");
+const yaml = require("js-yaml");
+
+module.exports = function ({ argv }) {
+  try {
+    const oasFiles = argv._.slice(1);
+    if (oasFiles.length < 2) {
+      return;
+    }
+
+    const merger = require("../../merger");
+
+    const oas = [];
+    for (let f of oasFiles) {
+      oas.push(yaml.load(fs.readFileSync(f)));
+    }
+
+    const combined = merger.apply(null, oas);
+    console.log(yaml.dump(combined));
+  } catch (e) {
+    console.error(`ERROR: ${e.message}`);
+    process.exit(1);
+  }
+};

package/merger.js

@@ -0,0 +1,99 @@
+const mergician = require("mergician");
+
+function merge(...objects) {
+  ensureNoComponentColissions(objects);
+  ensureNoPathColissions(objects);
+
+  // Do the merge
+  let combinedSpec = {};
+
+  // Values that should be overwritten
+  const overwriteMerge = mergician({ dedupArrays: true });
+  const overwriteSections = ["openapi", "info", "servers", "externalDocs"];
+  for (let section of overwriteSections) {
+    combinedSpec = mergeSection(combinedSpec, overwriteMerge, objects, section);
+  }
+
+  // Values that should be appended
+  const appendMerge = mergician({ appendArrays: true, dedupArrays: true });
+  const appendSections = ["paths", "components", "security", "tags"];
+  for (let section of appendSections) {
+    combinedSpec = mergeSection(combinedSpec, appendMerge, objects, section);
+  }
+
+  return combinedSpec;
+}
+
+function mergeSection(spec, merger, objects, section) {
+  return Object.assign(
+    spec,
+    merger.apply(
+      null,
+      objects
+        .map((o) => {
+          if (!o[section]) {
+            return null;
+          }
+          const r = {};
+          r[section] = o[section];
+          return r;
+        })
+        .filter(Boolean)
+    )
+  );
+}
+
+function ensureNoComponentColissions(objects) {
+  const componentList = {};
+  // Fetch the first two levels of components
+  for (const object of objects) {
+    if (object.components) {
+      for (let type in object.components) {
+        for (item in object.components[type]) {
+          componentList[`components.${type}.${item}`] =
+            componentList[`components.${type}.${item}`] || [];
+          componentList[`components.${type}.${item}`].push(object.info.title);
+        }
+      }
+    }
+  }
+
+  for (let component in componentList) {
+    const value = componentList[component];
+    if (value.length > 1) {
+      throw new Error(
+        `Duplicate component detected: ${component} (${value.join(", ")})`
+      );
+    }
+  }
+}
+
+function ensureNoPathColissions(objects) {
+  const actionList = {};
+  // Build a map of normalised paths to HTTP verb mapping
+  for (const object of objects) {
+    for (let path in object.paths) {
+      // Normalise the path
+      const normalisedPath = path.replace(/\{\w+\}/g, "{VAR}");
+      for (let verb in object.paths[path]) {
+        const k = `${verb.toUpperCase()} ${normalisedPath}`;
+        actionList[k] = actionList[k] || [];
+        actionList[k].push(object.info.title);
+      }
+    }
+  }
+
+  for (let action in actionList) {
+    const value = actionList[action];
+    if (value.length > 1) {
+      throw new Error(
+        `Duplicate path detected: ${action} (${value.join(", ")})`
+      );
+    }
+  }
+}
+
+module.exports = Object.assign(merge, {
+  ensureNoComponentColissions,
+  ensureNoPathColissions,
+});

package/merger.test.js

@@ -0,0 +1,219 @@
+const {
+  ensureNoComponentColissions,
+  ensureNoPathColissions,
+} = require("./merger");
+const merger = require("./merger");
+
+const FooSchema = { type: "string" };
+const BarSchema = { type: "boolean" };
+
+describe("#ensureNoComponentColissions", () => {
+  it("does not throw when schemas have different prefixes", () => {
+    expect(
+      ensureNoComponentColissions([
+        { info: { title: "One" }, components: { schemas: { FooSchema } } },
+        {
+          info: { title: "Two" },
+          components: { requestBodies: { FooSchema } },
+        },
+      ])
+    ).toBe(undefined);
+  });
+
+  it("does not throw when schemas have different prefixes", () => {
+    expect(
+      ensureNoComponentColissions([
+        { info: { title: "One" }, components: { schemas: { FooSchema } } },
+        { info: { title: "Two" }, components: { schemas: { BarSchema } } },
+      ])
+    ).toBe(undefined);
+  });
+
+  it("throws when two components have the same name", () => {
+    expect(() => {
+      ensureNoComponentColissions([
+        { info: { title: "One" }, components: { schemas: { FooSchema } } },
+        { info: { title: "Two" }, components: { schemas: { FooSchema } } },
+      ]);
+    }).toThrow(
+      new Error(
+        "Duplicate component detected: components.schemas.FooSchema (One, Two)"
+      )
+    );
+  });
+
+  it("throws when two components have the same name (multiple schemas)", () => {
+    expect(() => {
+      ensureNoComponentColissions([
+        { info: { title: "One" }, components: { schemas: { BarSchema } } },
+        {
+          info: { title: "Two" },
+          components: { schemas: { FooSchema, BarSchema } },
+        },
+      ]);
+    }).toThrow(
+      new Error(
+        "Duplicate component detected: components.schemas.BarSchema (One, Two)"
+      )
+    );
+  });
+});
+
+describe("path collisions", () => {
+  it("does not throw with overlapping paths and different verbs", () => {
+    expect(
+      ensureNoPathColissions([
+        { info: { title: "One" }, paths: { "/foo": { get: {} } } },
+        { info: { title: "Two" }, paths: { "/foo": { post: {} } } },
+      ])
+    ).toBe(undefined);
+  });
+
+  it("throws when a path has multiple implementations for a verb (static)", () => {
+    expect(() => {
+      ensureNoPathColissions([
+        { info: { title: "One" }, paths: { "/foo": { get: {} } } },
+        { info: { title: "Two" }, paths: { "/foo": { get: {} } } },
+      ]);
+    }).toThrow(new Error("Duplicate path detected: GET /foo (One, Two)"));
+  });
+
+  it("throws when a path has multiple implementations for a verb (regex)", () => {
+    expect(() => {
+      ensureNoPathColissions([
+        { info: { title: "One" }, paths: { "/users/{userId}": { get: {} } } },
+        { info: { title: "Two" }, paths: { "/users/{id}": { get: {} } } },
+      ]);
+    }).toThrow(
+      new Error("Duplicate path detected: GET /users/{VAR} (One, Two)")
+    );
+  });
+
+  it("throws with multiple variables in the path", () => {
+    expect(() => {
+      ensureNoPathColissions([
+        {
+          info: { title: "One" },
+          paths: { "/users/{userId}/purchases/{id}": { get: {} } },
+        },
+        {
+          info: { title: "Two" },
+          paths: {
+            "/foo": { post: {} },
+            "/users/{id}/purchases/{purchaseId}": { get: {} },
+          },
+        },
+      ]);
+    }).toThrow(
+      new Error(
+        "Duplicate path detected: GET /users/{VAR}/purchases/{VAR} (One, Two)"
+      )
+    );
+  });
+});
+
+describe("uses the last provided value for:", () => {
+  it("openapi", () => {
+    expect(merger({ openapi: "3.0.3" }, { openapi: "3.1.0" })).toEqual({
+      openapi: "3.1.0",
+    });
+  });
+
+  it("info", () => {
+    expect(
+      merger({ info: { title: "OAS One" } }, { info: { title: "OAS Two" } })
+    ).toEqual({ info: { title: "OAS Two" } });
+  });
+
+  it("servers", () => {
+    expect(
+      merger(
+        {
+          servers: [
+            { url: "https://example.com", description: "My API Description" },
+          ],
+        },
+        {
+          servers: [
+            {
+              url: "https://api.example.com",
+              description: "Overwritten value",
+            },
+          ],
+        }
+      )
+    ).toEqual({
+      servers: [
+        { url: "https://api.example.com", description: "Overwritten value" },
+      ],
+    });
+  });
+});
+
+describe("concatenates values for:", () => {
+  it("tags", () => {
+    expect(
+      merger(
+        { tags: [{ name: "One", description: "Description one" }] },
+        { tags: [{ name: "Two", description: "Description two" }] }
+      )
+    ).toEqual({
+      tags: [
+        { name: "One", description: "Description one" },
+        { name: "Two", description: "Description two" },
+      ],
+    });
+  });
+
+  it("paths", () => {
+    expect(
+      merger(
+        {
+          info: { title: "One" },
+          paths: { "/users": { get: { operationId: "list-users" } } },
+        },
+        {
+          info: { title: "Two" },
+          paths: { "/users": { post: { operationId: "create-user" } } },
+        }
+      )
+    ).toMatchObject({
+      paths: {
+        "/users": {
+          get: { operationId: "list-users" },
+          post: { operationId: "create-user" },
+        },
+      },
+    });
+  });
+
+  it("security", () => {
+    expect(
+      merger(
+        { security: [{ basicAuth: { type: "http", scheme: "basic" } }] },
+        {
+          security: [
+            {
+              bearerAuth: {
+                type: "http",
+                scheme: "bearer",
+                bearerFormat: "JWT",
+              },
+            },
+          ],
+        }
+      )
+    ).toEqual({
+      security: [
+        { basicAuth: { type: "http", scheme: "basic" } },
+        {
+          bearerAuth: {
+            type: "http",
+            scheme: "bearer",
+            bearerFormat: "JWT",
+          },
+        },
+      ],
+    });
+  });
+});

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "oas-toolkit",
+  "version": "0.1.0",
+  "description": "",
+  "main": "index.js",
+  "bin": {
+    "oas-toolkit": "./cli/bin.js"
+  },
+  "scripts": {
+    "test": "jest"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "jest": "^29.5.0"
+  },
+  "dependencies": {
+    "@apidevtools/json-schema-ref-parser": "^10.1.0",
+    "debug": "^4.3.4",
+    "js-yaml": "^4.1.0",
+    "jsonpath-plus": "^7.2.0",
+    "mergician": "^1.1.0",
+    "yargs": "^17.7.1"
+  }
+}