feat: resolve externalValue

src/resolver.js

@@ -25,6 +25,20 @@ export function clearCache() {
   plugins.refs.clearCache();
 }
 
+export function makeFetchRaw(http, opts = {}) {
+  const { requestInterceptor, responseInterceptor } = opts;
+  // Set credentials with 'http.withCredentials' value
+  const credentials = http.withCredentials ? 'include' : 'same-origin';
+  return (docPath) =>
+    http({
+      url: docPath,
+      loadSpec: true,
+      requestInterceptor,
+      responseInterceptor,
+      credentials,
+    }).then((res) => res.text);
+}
+
 export default function resolve(obj) {
   const {
     fetch,
@@ -66,8 +80,13 @@ export default function resolve(obj) {
 
     // Build a json-fetcher ( ie: give it a URL and get json out )
     plugins.refs.fetchJSON = makeFetchJSON(http, { requestInterceptor, responseInterceptor });
+    // Build a raw-fetcher ( ie: give it a URL and get raw text out )
+    plugins.externalValue.fetchRaw = makeFetchRaw(http, {
+      requestInterceptor,
+      responseInterceptor,
+    });
 
-    const plugs = [plugins.refs];
+    const plugs = [plugins.refs, plugins.externalValue];
 
     if (typeof parameterMacro === 'function') {
       plugs.push(plugins.parameters);

src/specmap/index.js

@@ -3,6 +3,7 @@ import noop from 'lodash/noop';
 
 import lib from './lib';
 import refs from './lib/refs';
+import externalValue from './lib/external-value';
 import allOf from './lib/all-of';
 import parameters from './lib/parameters';
 import properties from './lib/properties';
@@ -396,6 +397,7 @@ export default function mapSpec(opts) {
 
 const plugins = {
   refs,
+  externalValue,
   allOf,
   parameters,
   properties,

src/specmap/lib/external-value.js

@@ -0,0 +1,202 @@
+import { fetch } from 'cross-fetch';
+
+import createError from './create-error';
+import lib from '.';
+
+const externalValuesCache = {};
+
+/**
+ * Clears all external value caches.
+ * @param  {String} url (optional) the original externalValue value of the cache item to be cleared.
+ * @api public
+ */
+ function clearCache(url) {
+  if (typeof url !== 'undefined') {
+    delete externalValuesCache[url];
+  } else {
+    Object.keys(externalValuesCache).forEach((key) => {
+      delete externalValuesCache[key];
+    });
+  }
+}
+
+/**
+ * Fetches a document.
+ * @param  {String} docPath the absolute URL of the document.
+ * @return {Promise}        a promise of the document content.
+ * @api public
+ */
+const fetchRaw = (url) => fetch(url).then((res) => res.text);
+
+const shouldResolveTestFn = [
+  // OAS 3.0 Response Media Type Examples externalValue
+  (path) =>
+    // ["paths", *, *, "responses", *, "content", *, "examples", *, "externalValue"]
+    path[0] === 'paths' &&
+    path[3] === 'responses' &&
+    path[5] === 'content' &&
+    path[7] === 'examples' &&
+    path[9] === 'externalValue',
+
+  // OAS 3.0 Request Body Media Type Examples externalValue
+  (path) =>
+    // ["paths", *, *, "requestBody", "content", *, "examples", *, "externalValue"]
+    path[0] === 'paths' &&
+    path[3] === 'requestBody' &&
+    path[4] === 'content' &&
+    path[6] === 'examples' &&
+    path[8] === 'externalValue',
+
+  // OAS 3.0 Parameter Examples externalValue
+  (path) =>
+    // ["paths", *, "parameters", *, "examples", *, "externalValue"]
+    path[0] === 'paths' &&
+    path[2] === 'parameters' &&
+    path[4] === 'examples' &&
+    path[6] === 'externalValue',
+  (path) =>
+    // ["paths", *, *, "parameters", *, "examples", *, "externalValue"]
+    path[0] === 'paths' &&
+    path[3] === 'parameters' &&
+    path[5] === 'examples' &&
+    path[7] === 'externalValue',
+  (path) =>
+    // ["paths", *, "parameters", *, "content", *, "examples", *, "externalValue"]
+    path[0] === 'paths' &&
+    path[2] === 'parameters' &&
+    path[4] === 'content' &&
+    path[6] === 'examples' &&
+    path[8] === 'externalValue',
+  (path) =>
+    // ["paths", *, *, "parameters", *, "content", *, "examples", *, "externalValue"]
+    path[0] === 'paths' &&
+    path[3] === 'parameters' &&
+    path[5] === 'content' &&
+    path[7] === 'examples' &&
+    path[9] === 'externalValue',
+];
+
+const shouldSkipResolution = (path) => !shouldResolveTestFn.some((fn) => fn(path));
+
+const ExternalValueError = createError('ExternalValueError', function cb(message, extra, oriError) {
+  this.originalError = oriError;
+  Object.assign(this, extra || {});
+});
+
+/**
+ * This plugin resolves externalValue keys.
+ * In order to do so it will use a cache in case the url was already requested.
+ * It will use the fetchRaw method in order get the raw content hosted on specified url.
+ * If successful retrieved it will replace the url with the actual value
+ */
+const plugin = {
+  key: 'externalValue',
+  plugin: (externalValue, _, fullPath) => {
+    const parent = fullPath.slice(0, -1);
+
+    if (shouldSkipResolution(fullPath)) {
+      return undefined;
+    }
+
+    if (typeof externalValue !== 'string') {
+      return new ExternalValueError('externalValue: must be a string', {
+        externalValue,
+        fullPath,
+      });
+    }
+
+    try {
+      let externalValueOrPromise = getExternalValue(externalValue, fullPath);
+      if (typeof externalValueOrPromise === 'undefined') {
+        externalValueOrPromise = new ExternalValueError(
+          `Could not resolve externalValue: ${externalValue}`,
+          {
+            externalValue,
+            fullPath,
+          }
+        );
+      }
+      // eslint-disable-next-line no-underscore-dangle
+      if (externalValueOrPromise.__value != null) {
+        // eslint-disable-next-line no-underscore-dangle
+        externalValueOrPromise = externalValueOrPromise.__value;
+      } else {
+        externalValueOrPromise = externalValueOrPromise.catch((e) => {
+          throw wrapError(e, {
+            externalValue,
+            fullPath,
+          });
+        });
+      }
+
+      if (externalValueOrPromise instanceof Error) {
+        return [lib.remove(fullPath), externalValueOrPromise];
+      }
+
+      const backupOriginalValuePatch = lib.add([...parent, '$externalValue'], externalValue)
+      const valuePatch = lib.replace([...parent, 'value'], externalValueOrPromise);
+      const cleanUpPatch = lib.remove(fullPath)
+      return [
+        backupOriginalValuePatch,
+        valuePatch,
+        cleanUpPatch
+      ];
+    } catch (err) {
+      return [
+        lib.remove(fullPath),
+        wrapError(err, {
+          externalValue,
+          fullPath,
+        }),
+      ];
+    }
+  },
+};
+const mod = Object.assign(plugin, {
+  wrapError,
+  clearCache,
+  ExternalValueError,
+  fetchRaw,
+  getExternalValue,
+});
+export default mod;
+
+/**
+ * Wraps an error as ExternalValueError.
+ * @param  {Error} e      the error.
+ * @param  {Object} extra (optional) optional data.
+ * @return {Error}        an instance of ExternalValueError.
+ * @api public
+ */
+function wrapError(e, extra) {
+  let message;
+
+  if (e && e.response && e.response.body) {
+    message = `${e.response.body.code} ${e.response.body.message}`;
+  } else {
+    message = e.message;
+  }
+
+  return new ExternalValueError(`Could not resolve externalValue: ${message}`, extra, e);
+}
+
+/**
+ * Fetches and caches a ExternalValue.
+ * @param  {String} docPath the absolute URL of the document.
+ * @return {Promise}        a promise of the document content.
+ * @api public
+ */
+function getExternalValue(url) {
+  const val = externalValuesCache[url];
+  if (val) {
+    return lib.isPromise(val) ? val : Promise.resolve(val);
+  }
+
+  // NOTE: we need to use `mod.fetchRaw` in order to be able to overwrite it.
+  // Any tips on how to make this cleaner, please ping!
+  externalValuesCache[url] = mod.fetchRaw(url).then((raw) => {
+    externalValuesCache[url] = raw;
+    return raw;
+  });
+  return externalValuesCache[url];
+}

test/specmap/external-value.js

@@ -0,0 +1,49 @@
+import xmock from 'xmock';
+
+import mapSpec, { plugins } from '../../src/specmap';
+
+const { externalValue } = plugins;
+
+describe('externalValue', () => {
+  let xapp;
+
+  beforeAll(() => {
+    xapp = xmock();
+  });
+
+  afterAll(() => {
+    xapp.restore();
+  });
+
+  beforeEach(() => {
+    externalValue.clearCache()
+  });
+
+  describe('ExternalValueError', () => {
+    test('should contain the externalValue error details', () => {
+      try {
+        throw new externalValue.ExternalValueError('Probe', {
+          externalValue: 'http://test.com/probe',
+          fullPath: "probe",
+        });
+      } catch (e) {
+        expect(e.toString()).toEqual('ExternalValueError: Probe');
+        expect(e.externalValue).toEqual('http://test.com/probe');
+        expect(e.fullPath).toEqual("probe");
+      }
+    });
+    test('.wrapError should wrap an error in ExternalValueError', () => {
+      try {
+        throw externalValue.wrapError(new Error('hi'), {
+          externalValue: 'http://test.com/probe',
+          fullPath: "probe",
+        });
+      } catch (e) {
+        expect(e.message).toMatch(/externalValue/);
+        expect(e.message).toMatch(/hi/);
+        expect(e.externalValue).toEqual('http://test.com/probe');
+        expect(e.fullPath).toEqual("probe");
+      }
+    });
+  });
+});