api 4.5.1 → 5.0.0-beta.2

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import type { OASDocument } from 'oas/@types/rmoas.types';
+interface SDKOptions {
+    cacheDir?: string;
+}
+declare const _default: (uri: string | OASDocument, opts?: SDKOptions) => any;
+export = _default;

package/dist/index.js

@@ -0,0 +1,276 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (_) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+var oas_1 = __importDefault(require("oas"));
+var core_1 = __importDefault(require("./core"));
+var cache_1 = __importDefault(require("./cache"));
+var packageInfo_1 = require("./packageInfo");
+var Sdk = /** @class */ (function () {
+    function Sdk(uri, opts) {
+        if (opts === void 0) { opts = {}; }
+        this.uri = uri;
+        this.userAgent = "".concat(packageInfo_1.PACKAGE_NAME, " (node)/").concat(packageInfo_1.PACKAGE_VERSION);
+        this.cacheDir = opts.cacheDir ? opts.cacheDir : false;
+    }
+    Sdk.prototype.load = function () {
+        var cache = new cache_1["default"](this.uri, this.cacheDir);
+        var userAgent = this.userAgent;
+        var core = new core_1["default"]();
+        core.setUserAgent(userAgent);
+        var isLoaded = false;
+        var isCached = cache.isCached();
+        var sdk = {};
+        /**
+         * Create dynamic accessors for every HTTP method that the OpenAPI specification supports.
+         *
+         * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-7}
+         * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-7}
+         */
+        function loadMethods() {
+            return ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']
+                .map(function (httpVerb) {
+                var _a;
+                return _a = {},
+                    _a[httpVerb] = (function (method, path) {
+                        var args = [];
+                        for (var _i = 2; _i < arguments.length; _i++) {
+                            args[_i - 2] = arguments[_i];
+                        }
+                        return core.fetch.apply(core, __spreadArray([path, method], args, false));
+                    }).bind(null, httpVerb),
+                    _a;
+            })
+                .reduce(function (prev, next) { return Object.assign(prev, next); });
+        }
+        /**
+         * Create dynamic accessors for every operation with a defined operation ID. If an operation
+         * does not have an operation ID it can be accessed by its `.method('/path')` accessor instead.
+         *
+         * @param spec
+         */
+        function loadOperations(spec) {
+            return Object.entries(spec.getPaths())
+                .map(function (_a) {
+                var operations = _a[1];
+                return Object.values(operations);
+            })
+                .reduce(function (prev, next) { return prev.concat(next); }, [])
+                .filter(function (operation) { return operation.hasOperationId(); })
+                .reduce(function (prev, next) {
+                var _a;
+                // `getOperationId()` creates dynamic operation IDs when one isn't available but we need
+                // to know here if we actually have one present or not. The `camelCase` option here also
+                // cleans up any `operationId` that we might have into something that can be used as a
+                // valid JS method.
+                var operationId = next.getOperationId({ camelCase: true });
+                return Object.assign(prev, (_a = {},
+                    _a[operationId] = (function (operation) {
+                        var args = [];
+                        for (var _i = 1; _i < arguments.length; _i++) {
+                            args[_i - 1] = arguments[_i];
+                        }
+                        return core.fetchOperation.apply(core, __spreadArray([operation], args, false));
+                    }).bind(null, next),
+                    _a));
+            }, {});
+        }
+        function loadFromCache() {
+            return __awaiter(this, void 0, void 0, function () {
+                var cachedSpec, spec;
+                return __generator(this, function (_a) {
+                    switch (_a.label) {
+                        case 0:
+                            if (!isCached) return [3 /*break*/, 2];
+                            return [4 /*yield*/, cache.get()];
+                        case 1:
+                            cachedSpec = _a.sent();
+                            return [3 /*break*/, 4];
+                        case 2: return [4 /*yield*/, cache.load()];
+                        case 3:
+                            cachedSpec = _a.sent();
+                            isCached = true;
+                            _a.label = 4;
+                        case 4:
+                            spec = new oas_1["default"](cachedSpec);
+                            core.setSpec(spec);
+                            sdk = Object.assign(sdk, __assign(__assign({}, loadMethods()), loadOperations(spec)));
+                            isLoaded = true;
+                            return [2 /*return*/];
+                    }
+                });
+            });
+        }
+        var sdkProxy = {
+            // @give this a better type than any
+            get: function (target, method) {
+                // Since auth returns a self-proxy, we **do not** want it to fall through into the async
+                // function below as when that'll happen, instead of returning a self-proxy, it'll end up
+                // returning a Promise. When that happens, chaining `sdk.auth().operationId()` will fail.
+                if (['auth', 'config'].includes(method)) {
+                    // @todo split this up so we have better types for `auth` and `config`
+                    return function () {
+                        var args = [];
+                        for (var _i = 0; _i < arguments.length; _i++) {
+                            args[_i] = arguments[_i];
+                        }
+                        return target[method].apply(this, args);
+                    };
+                }
+                return function () {
+                    var args = [];
+                    for (var _i = 0; _i < arguments.length; _i++) {
+                        args[_i] = arguments[_i];
+                    }
+                    return __awaiter(this, void 0, void 0, function () {
+                        return __generator(this, function (_a) {
+                            switch (_a.label) {
+                                case 0:
+                                    if (!!(method in target)) return [3 /*break*/, 2];
+                                    // If this method doesn't exist on the proxy, have we loaded the SDK? If we have, then
+                                    // this method isn't valid.
+                                    if (isLoaded) {
+                                        throw new Error("Sorry, `".concat(method, "` does not appear to be a valid operation on this API."));
+                                    }
+                                    return [4 /*yield*/, loadFromCache()];
+                                case 1:
+                                    _a.sent();
+                                    // If after loading the SDK and this method still doesn't exist, then it's not real!
+                                    if (!(method in sdk)) {
+                                        throw new Error("Sorry, `".concat(method, "` does not appear to be a valid operation on this API."));
+                                    }
+                                    // @todo give sdk a better type
+                                    return [2 /*return*/, sdk[method].apply(this, args)];
+                                case 2: return [2 /*return*/, target[method].apply(this, args)];
+                            }
+                        });
+                    });
+                };
+            }
+        };
+        sdk = {
+            /**
+             * If the API you're using requires authentication you can supply the required credentials
+             * through this method and the library will magically determine how they should be used
+             * within your API request.
+             *
+             * With the exception of OpenID and MutualTLS, it supports all forms of authentication
+             * supported by the OpenAPI specification.
+             *
+             * @example <caption>HTTP Basic auth</caption>
+             * sdk.auth('username', 'password');
+             *
+             * @example <caption>Bearer tokens (HTTP or OAuth 2)</caption>
+             * sdk.auth('myBearerToken');
+             *
+             * @example <caption>API Keys</caption>
+             * sdk.auth('myApiKey');
+             *
+             * @see {@link https://spec.openapis.org/oas/v3.0.3#fixed-fields-22}
+             * @see {@link https://spec.openapis.org/oas/v3.1.0#fixed-fields-22}
+             * @param values Your auth credentials for the API. Can specify up to two strings or numbers.
+             */
+            auth: function () {
+                var values = [];
+                for (var _i = 0; _i < arguments.length; _i++) {
+                    values[_i] = arguments[_i];
+                }
+                core.setAuth.apply(core, values);
+            },
+            /**
+             * Optionally configure various options, such as response parsing, that the SDK allows.
+             *
+             * @param config Object of supported SDK options and toggles.
+             * @param config.parseResponse If responses are parsed according to its `Content-Type` header.
+             */
+            config: function (config) {
+                core.setConfig(config);
+            },
+            /**
+             * If the API you're using offers alternate server URLs, and server variables, you can tell
+             * the SDK which one to use with this method. To use it you can supply either one of the
+             * server URLs that are contained within the OpenAPI definition (along with any server
+             * variables), or you can pass it a fully qualified URL to use (that may or may not exist
+             * within the OpenAPI definition).
+             *
+             * @example <caption>Server URL with server variables</caption>
+             * sdk.server('https://{region}.api.example.com/{basePath}', {
+             *   name: 'eu',
+             *   basePath: 'v14',
+             * });
+             *
+             * @example <caption>Fully qualified server URL</caption>
+             * sdk.server('https://eu.api.example.com/v14');
+             *
+             * @param url Server URL
+             * @param variables An object of variables to replace into the server URL.
+             */
+            server: function (url, variables) {
+                if (variables === void 0) { variables = {}; }
+                core.setServer(url, variables);
+            }
+        };
+        return new Proxy(sdk, sdkProxy);
+    };
+    return Sdk;
+}());
+module.exports = function (uri, opts) {
+    if (opts === void 0) { opts = {}; }
+    return new Sdk(uri, opts).load();
+};

package/dist/packageInfo.d.ts

@@ -0,0 +1,2 @@
+export declare const PACKAGE_NAME = "api";
+export declare const PACKAGE_VERSION = "5.0.0-beta.2";

package/dist/packageInfo.js

@@ -0,0 +1,6 @@
+"use strict";
+exports.__esModule = true;
+exports.PACKAGE_VERSION = exports.PACKAGE_NAME = void 0;
+// This file is automatically updated by the build script.
+exports.PACKAGE_NAME = 'api';
+exports.PACKAGE_VERSION = '5.0.0-beta.2';

package/package.json

@@ -1,56 +1,95 @@
 {
   "name": "api",
-  "version": "4.5.1",
-  "description": "Generate an SDK from an OpenAPI definition",
-  "main": "src/index.js",
+  "version": "5.0.0-beta.2",
+  "description": "Magical SDK generation from an OpenAPI definition 🪄",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "api": "./bin/api"
+  },
   "scripts": {
-    "lint": "eslint .",
-    "pretest": "npm run lint",
-    "prettier": "prettier --list-different --write \"./**/**.js\"",
-    "test": "jest --coverage"
+    "build": "tsc",
+    "debug:bin": "node -r ts-node/register src/bin.ts",
+    "prebuild": "rm -rf dist/; npm run prebuild.packageConfig",
+    "prebuild.packageConfig": "node -p \"'// This file is automatically updated by the build script.\\nexport const PACKAGE_NAME = \\'' + require('./package.json').name + '\\';\\nexport const PACKAGE_VERSION = \\'' + require('./package.json').version + '\\';'\" > src/packageInfo.ts; git add src/packageInfo.ts",
+    "prepack": "npm run build",
+    "test": "nyc mocha \"test/**/*.test.ts\""
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/readmeio/api.git",
     "directory": "packages/api"
   },
+  "homepage": "https://api.readme.dev",
   "bugs": {
     "url": "https://github.com/readmeio/api/issues"
   },
   "author": "Jon Ursenbach <jon@readme.io>",
   "license": "MIT",
   "engines": {
-    "node": "^12 || ^14 || ^16"
+    "node": ">=14"
   },
+  "keywords": [
+    "api",
+    "openapi",
+    "sdk",
+    "swagger"
+  ],
   "dependencies": {
-    "@readme/oas-to-har": "^16.1.0",
-    "@readme/openapi-parser": "^2.1.0",
+    "@readme/oas-to-har": "^17.0.8",
+    "@readme/openapi-parser": "^2.2.0",
+    "chalk": "^4.1.2",
+    "commander": "^9.2.0",
     "datauri": "^4.1.0",
-    "fetch-har": "^5.0.5",
+    "execa": "^5.1.1",
+    "fetch-har": "^8.0.3",
+    "figures": "^3.2.0",
     "find-cache-dir": "^3.3.1",
-    "form-data": "^4.0.0",
-    "get-stream": "^6.0.0",
+    "form-data-encoder": "^1.7.2",
+    "formdata-node": "^4.3.2",
+    "get-stream": "^6.0.1",
+    "isomorphic-fetch": "^3.0.0",
     "js-yaml": "^4.1.0",
+    "json-schema-to-typescript": "^10.1.5",
+    "json-schema-traverse": "^1.0.0",
+    "lodash.merge": "^4.6.2",
     "make-dir": "^3.1.0",
-    "mimer": "^2.0.2",
-    "node-fetch": "^2.6.0",
-    "oas": "^18.1.0"
+    "oas": "^18.3.3",
+    "object-hash": "^3.0.0",
+    "ora": "^5.4.1",
+    "prompts": "^2.4.2",
+    "ssri": "^9.0.0",
+    "ts-morph": "^15.1.0",
+    "validate-npm-package-name": "^4.0.0"
   },
   "devDependencies": {
-    "@readme/eslint-config": "^8.0.2",
-    "@readme/oas-examples": "^4.3.3",
-    "eslint": "^8.3.0",
-    "jest": "^27.3.1",
-    "memfs": "^3.2.4",
-    "nock": "^13.1.3",
-    "prettier": "^2.4.1"
+    "@readme/oas-examples": "^5.4.1",
+    "@types/chai": "^4.3.1",
+    "@types/find-cache-dir": "^3.2.1",
+    "@types/js-yaml": "^4.0.5",
+    "@types/lodash.merge": "^4.6.7",
+    "@types/mocha": "^9.1.1",
+    "@types/object-hash": "^2.2.1",
+    "@types/prompts": "^2.0.14",
+    "@types/sinon-chai": "^3.2.8",
+    "@types/ssri": "^7.1.1",
+    "@types/validate-npm-package-name": "^4.0.0",
+    "chai": "^4.3.6",
+    "fetch-mock": "^9.11.0",
+    "mocha": "^10.0.0",
+    "mock-require": "^3.0.3",
+    "nyc": "^15.1.0",
+    "sinon": "^14.0.0",
+    "sinon-chai": "^3.7.0",
+    "typescript": "^4.7.4",
+    "unique-temp-dir": "^1.0.0"
   },
   "prettier": "@readme/eslint-config/prettier",
-  "jest": {
-    "testPathIgnorePatterns": [
-      "__tests__/__fixtures__/",
-      ".api-test/"
+  "nyc": {
+    "exclude": [
+      "dist/",
+      "test/"
     ]
   },
-  "gitHead": "5c3490291498c1ac7f2f9dfe2ad99afff9010689"
+  "gitHead": "aa738b1bf46b447afed38507d3fc49acbbad6309"
 }

package/src/.sink.d.ts

@@ -0,0 +1 @@
+declare module 'form-data-encoder';

package/src/bin.ts

@@ -0,0 +1,20 @@
+import { Command } from 'commander';
+import * as pkg from './packageInfo';
+import commands from './cli/commands';
+
+(async () => {
+  const program = new Command();
+  program.name(pkg.PACKAGE_NAME);
+  program.version(pkg.PACKAGE_VERSION);
+
+  /**
+   * Instead of using Commander's `executableDir` API for loading in external command files we're
+   * programatically doing it like this because it's cleaner for us to let Commander manage option
+   * and argument parsing within this file than having each command  manage that itself.
+   */
+  Object.entries(commands).forEach(([, cmd]: [string, Command]) => {
+    program.addCommand(cmd);
+  });
+
+  await program.parseAsync(process.argv);
+})();

package/src/cache.ts

@@ -0,0 +1,212 @@
+import type { OASDocument } from 'oas/@types/rmoas.types';
+
+import 'isomorphic-fetch';
+import OpenAPIParser from '@readme/openapi-parser';
+import crypto from 'crypto';
+import findCacheDir from 'find-cache-dir';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import makeDir from 'make-dir';
+
+import { PACKAGE_NAME } from './packageInfo';
+
+import Fetcher from './fetcher';
+
+type CacheStore = Record<
+  string,
+  {
+    hash: string;
+    path?: string; // Deprecated in v4.5.0 in favor of `hash`.
+    original: string | OASDocument;
+    title?: string;
+    version?: string;
+  }
+>;
+
+export default class Cache {
+  static dir: string;
+
+  static cacheStore: string;
+
+  static specsCache: string;
+
+  uri: string | OASDocument;
+
+  uriHash: string;
+
+  cached: false | CacheStore;
+
+  fetcher: Fetcher;
+
+  constructor(uri: string | OASDocument, cacheDir: string | false = false) {
+    Cache.setCacheDir(cacheDir);
+    Cache.cacheStore = path.join(Cache.dir, 'cache.json');
+    Cache.specsCache = path.join(Cache.dir, 'specs');
+
+    this.fetcher = new Fetcher(uri);
+
+    this.uri = this.fetcher.uri;
+    this.uriHash = Cache.getCacheHash(this.uri);
+
+    // This should default to false so we have awareness if we've looked at the cache yet.
+    this.cached = false;
+  }
+
+  static getCacheHash(file: string | OASDocument) {
+    let data: string;
+    if (typeof file === 'object') {
+      // Under certain unit testing circumstances, we might be supplying the class with a raw JSON
+      // object so we'll need to convert it to a string in order to hand it off to the crypto
+      // module.
+      data = JSON.stringify(file);
+    } else {
+      data = file;
+    }
+
+    return crypto.createHash('md5').update(data).digest('hex');
+  }
+
+  static setCacheDir(dir?: string | false) {
+    if (dir) {
+      Cache.dir = dir;
+      return;
+    } else if (Cache.dir) {
+      // If we already have a cache dir set and aren't explicitly it to something new then we
+      // shouldn't overwrite what we've already got.
+      return;
+    }
+
+    Cache.dir = findCacheDir({ name: PACKAGE_NAME });
+    if (typeof Cache.dir === 'undefined') {
+      // The `find-cache-dir` module returns `undefined` if the `node_modules/` directory isn't
+      // writable, or there's no `package.json` in the root-most directory. If this happens, we can
+      // instead adhoc create a cache directory in the users OS temp directory and store our data
+      // there.
+      //
+      // @link https://github.com/avajs/find-cache-dir/issues/29
+      Cache.dir = makeDir.sync(path.join(os.tmpdir(), PACKAGE_NAME));
+    }
+  }
+
+  static async reset() {
+    if (Cache.cacheStore) {
+      await fs.promises.rm(Cache.cacheStore).catch(() => {
+        // no-op
+      });
+    }
+
+    if (Cache.specsCache) {
+      await fs.promises.rm(Cache.specsCache, { recursive: true }).catch(() => {
+        // no-op
+      });
+    }
+  }
+
+  static validate(json: any) {
+    if (json.swagger) {
+      throw new Error('Sorry, this module only supports OpenAPI definitions.');
+    }
+
+    // The `validate` method handles dereferencing for us.
+    return OpenAPIParser.validate(json, {
+      dereference: {
+        // If circular `$refs` are ignored they'll remain in the API definition as `$ref: String`.
+        // This allows us to not only do easy circular reference detection but also stringify and
+        // save dereferenced API definitions back into the cache directory.
+        circular: 'ignore',
+      },
+    }).catch(err => {
+      if (/is not a valid openapi definition/i.test(err.message)) {
+        throw new Error("Sorry, that doesn't look like a valid OpenAPI definition.");
+      }
+
+      throw err;
+    });
+  }
+
+  isCached() {
+    const cache = this.getCache();
+    return cache && this.uriHash in cache;
+  }
+
+  getCache() {
+    if (typeof this.cached === 'object') {
+      return this.cached;
+    }
+
+    this.cached = {};
+
+    if (fs.existsSync(Cache.cacheStore)) {
+      this.cached = JSON.parse(fs.readFileSync(Cache.cacheStore, 'utf8')) as CacheStore;
+    }
+
+    return this.cached;
+  }
+
+  get() {
+    // If the class was supplied a raw object, just go ahead and bypass the caching system and
+    // return that.
+    if (typeof this.uri === 'object') {
+      return this.uri;
+    }
+
+    if (!this.isCached()) {
+      throw new Error(`${this.uri} has not been cached yet and must do so before being retrieved.`);
+    }
+
+    const cache = this.getCache();
+
+    // Prior to v4.5.0 we were putting a fully resolved path to the API definition in the cache
+    // store but if you had specified a custom caching directory and would generate the cache on
+    // your system, that filepath would obviously not be the same in other environments. For this
+    // reason the `path` was removed from the cache store in favor of storing the `hash` instead.
+    //
+    // If we still have `path` in the config cache for backwards compatibility we should use it.
+    if ('path' in cache[this.uriHash]) {
+      return JSON.parse(fs.readFileSync(cache[this.uriHash].path, 'utf8'));
+    }
+
+    return JSON.parse(fs.readFileSync(path.join(Cache.specsCache, `${cache[this.uriHash].hash}.json`), 'utf8'));
+  }
+
+  async load() {
+    // If the class was supplied a raw object, just go ahead and bypass the caching system and
+    // return that.
+    if (typeof this.uri === 'object') {
+      return this.uri;
+    }
+
+    return this.fetcher.load().then(async spec => this.save(spec));
+  }
+
+  save(spec: OASDocument) {
+    if (!fs.existsSync(Cache.dir)) {
+      fs.mkdirSync(Cache.dir, { recursive: true });
+    }
+
+    if (!fs.existsSync(Cache.specsCache)) {
+      fs.mkdirSync(Cache.specsCache, { recursive: true });
+    }
+
+    const cache = this.getCache();
+    if (!(this.uriHash in cache)) {
+      const saved = JSON.stringify(spec, null, 2);
+      const fileHash = crypto.createHash('md5').update(saved).digest('hex');
+
+      cache[this.uriHash] = {
+        hash: fileHash,
+        original: this.uri,
+        title: 'title' in spec.info ? spec.info.title : undefined,
+        version: 'version' in spec.info ? spec.info.version : undefined,
+      };
+
+      fs.writeFileSync(path.join(Cache.specsCache, `${fileHash}.json`), saved);
+      fs.writeFileSync(Cache.cacheStore, JSON.stringify(cache, null, 2));
+
+      this.cached = cache;
+    }
+
+    return spec;
+  }
+}