feat(oas3): support explode query parameters

Author: kylef

packages/fury-adapter-oas3-parser/CHANGELOG.md

@@ -2,8 +2,13 @@
 
 ## Master
 
+### Enhancements
+
 - Support for `servers` in `Path Item Object` and `Operation Object`
 
+- 'Parameter Object' 'explode' style is partially supported, it can be used
+  with query parameters.
+
 ## 0.11.0 (2020-04-20)
 
 ### Enhancements

packages/fury-adapter-oas3-parser/STATUS.md

@@ -122,7 +122,7 @@ Key:
 | Field Name | Support |
 |:--|:--|
 | style | ✕ |
-| explode | ✕ |
+| explode | ~ |
 | allowReserved | ✕ |
 | schema | ✕ |
 | example | ✕ |

packages/fury-adapter-oas3-parser/lib/parser/oas/parseOperationObject.js

@@ -75,7 +75,14 @@ function hrefVariablesFromParameters(namespace, parameters) {
 
 function hrefFromParameters(path, queryParameters) {
   const href = path.clone();
-  const queryString = queryParameters.keys().join(',');
+  const keys = queryParameters.map((value, key, member) => {
+    if (member.explode) {
+      return `${key.toValue()}*`;
+    }
+
+    return key.toValue();
+  });
+  const queryString = keys.join(',');
   href.content += `{?${queryString}}`;
   return href;
 }

packages/fury-adapter-oas3-parser/lib/parser/oas/parseParameterObject.js

@@ -16,7 +16,7 @@ const parseBoolean = require('../parseBoolean');
 const name = 'Parameter Object';
 const requiredKeys = ['name', 'in'];
 const unsupportedKeys = [
-  'deprecated', 'allowEmptyValue', 'style', 'explode', 'allowReserved',
+  'deprecated', 'allowEmptyValue', 'style', 'allowReserved',
   'schema', 'examples', 'content',
 ];
 const isUnsupportedKey = R.anyPass(R.map(hasKey, unsupportedKeys));
@@ -60,6 +60,11 @@ function validateRequiredForPathParameter(context, object, parameter) {
   return parseResult;
 }
 
+const hasExplodeWithoutQueryIn = R.allPass([
+  object => object.getValue('explode') === true,
+  object => object.getValue('in') !== 'query',
+]);
+
 /**
  * Parse Parameter Object
  *
@@ -95,6 +100,7 @@ function parseParameterObject(context, object) {
     [hasKey('in'), parseIn],
     [hasKey('description'), parseString(context, name, false)],
     [hasKey('required'), parseBoolean(context, name, false)],
+    [hasKey('explode'), parseBoolean(context, name, false)],
     [hasKey('example'), e => e.clone()],
 
     [isUnsupportedKey, createUnsupportedMemberWarning(namespace, name)],
@@ -137,12 +143,25 @@ function parseParameterObject(context, object) {
     R.when(nameContainsReservedCharacter, createUnsupportedNameError),
     R.when(nameContainsReservedHeaderName, createReservedHeaderNamesWarning));
 
+  const createUnsupportedExplodeWarning = (object) => {
+    const member = object.getMember('explode');
+    const inValue = object.getValue('in');
+    const message = `'${name}' '${member.key.toValue()}' is unsupported in ${inValue}`;
+    return createWarning(namespace, message, member.key);
+  };
+
+  const attachWarning = R.curry((createWarning, value) => {
+    const warning = createWarning(value);
+    return new namespace.elements.ParseResult([value, warning]);
+  });
+
   const parseParameter = pipeParseResult(namespace,
     parseObject(context, name, parseMember, requiredKeys),
     R.when(hasLocation('path'), R.curry(validateRequiredForPathParameter)(context, object)),
     R.when(hasLocation('path'), validatePathName),
     R.when(hasLocation('query'), sanitizeQueryName),
     R.when(hasLocation('header'), validateHeaderName),
+    R.when(hasExplodeWithoutQueryIn, attachWarning(createUnsupportedExplodeWarning)),
     (parameter) => {
       const example = parameter.get('example');
       const member = new namespace.elements.Member(parameter.get('name'), example);
@@ -159,6 +178,7 @@ function parseParameterObject(context, object) {
       }
 
       member.in = parameter.getValue('in');
+      member.explode = parameter.getValue('explode');
 
       return member;
     });

packages/fury-adapter-oas3-parser/lib/parser/oas/parseParameterObjects.js

@@ -29,7 +29,11 @@ function parseParameterObjects(context, name, array) {
 
   // Convert an array of parameters into the correct types
   const convertParameters = R.cond([
-    [isPathOrQuery, member => new namespace.elements.HrefVariables(member.value.clone().content)],
+    [isPathOrQuery, member => new namespace.elements.HrefVariables(member.value.content.map((element) => {
+      const member = element.clone();
+      member.explode = element.explode;
+      return member;
+    }))],
     // FIXME when headers and cookies are supported these should be converted
     [R.T, member => member.clone()],
   ]);

packages/fury-adapter-oas3-parser/lib/parser/oas/parsePathItemObject.js

@@ -108,7 +108,15 @@ function hrefFromParameters(path, parameters) {
   const href = path.clone();
 
   if (parameters && parameters.get('query')) {
-    const queryString = parameters.get('query').keys().join(',');
+    const queryString = parameters.get('query')
+      .map((value, key, member) => {
+        if (member.explode) {
+          return `${key.toValue()}*`;
+        }
+
+        return key.toValue();
+      })
+      .join(',');
     href.content += `{?${queryString}}`;
   }
 

packages/fury-adapter-oas3-parser/test/unit/parser/oas/parseOperationObject-test.js

@@ -322,6 +322,27 @@ describe('Operation Object', () => {
         expect(transition.href.toValue()).to.equal('/{?categories}');
       });
 
+      it('exposes query parameter in href with explode', () => {
+        const operation = new namespace.elements.Member('get', {
+          parameters: [
+            {
+              name: 'categories',
+              in: 'query',
+              explode: true,
+            },
+          ],
+          responses: {},
+        });
+
+        const parseResult = parse(context, path, operation);
+
+        expect(parseResult.length).to.equal(1);
+        expect(parseResult.get(0)).to.be.instanceof(namespace.elements.Transition);
+
+        const transition = parseResult.get(0);
+        expect(transition.href.toValue()).to.equal('/{?categories*}');
+      });
+
       it('exposes multiple query parameter in href', () => {
         const operation = new namespace.elements.Member('get', {
           parameters: [

packages/fury-adapter-oas3-parser/test/unit/parser/oas/parseParameterObject-test.js

@@ -317,6 +317,45 @@ describe('Parameter Object', () => {
     });
   });
 
+  describe('#explode', () => {
+    it('provides a warning when explode is not a boolean', () => {
+      const parameter = new namespace.elements.Object({
+        name: 'example',
+        in: 'query',
+        explode: 1,
+      });
+
+      const parseResult = parse(context, parameter);
+      expect(parseResult.length).to.equal(2);
+      expect(parseResult).to.contain.warning("'Parameter Object' 'explode' is not a boolean");
+    });
+
+    it('provides an unsupported warning when explode is used in header parameter', () => {
+      const parameter = new namespace.elements.Object({
+        name: 'example',
+        in: 'header',
+        explode: true,
+      });
+
+      const parseResult = parse(context, parameter);
+      expect(parseResult.length).to.equal(2);
+      expect(parseResult).to.contain.warning("'Parameter Object' 'explode' is unsupported in header");
+    });
+
+    it('provides an unsupported warning when explode is used in path parameter', () => {
+      const parameter = new namespace.elements.Object({
+        name: 'example',
+        in: 'path',
+        required: true,
+        explode: true,
+      });
+
+      const parseResult = parse(context, parameter);
+      expect(parseResult.length).to.equal(2);
+      expect(parseResult).to.contain.warning("'Parameter Object' 'explode' is unsupported in path");
+    });
+  });
+
   describe('#required', () => {
     it('create typeAttribute required', () => {
       const parameter = new namespace.elements.Object({
@@ -467,18 +506,6 @@ describe('Parameter Object', () => {
       expect(parseResult).to.contain.warning("'Parameter Object' contains unsupported key 'style'");
     });
 
-    it('provides warning for unsupported explode property', () => {
-      const parameter = new namespace.elements.Object({
-        name: 'example',
-        in: 'query',
-        explode: true,
-      });
-
-      const parseResult = parse(context, parameter);
-
-      expect(parseResult).to.contain.warning("'Parameter Object' contains unsupported key 'explode'");
-    });
-
     it('provides warning for unsupported allowReserved property', () => {
       const parameter = new namespace.elements.Object({
         name: 'example',

packages/fury-adapter-oas3-parser/test/unit/parser/oas/parsePathItemObject-test.js

@@ -226,6 +226,26 @@ describe('Path Item Object', () => {
         expect(resource.href.toValue()).to.equal('/{?categories}');
       });
 
+      it('exposes query parameter in href with explode', () => {
+        const path = new namespace.elements.Member('/', {
+          parameters: [
+            {
+              name: 'categories',
+              in: 'query',
+              explode: true,
+            },
+          ],
+        });
+
+        const parseResult = parse(context, path);
+
+        expect(parseResult.length).to.equal(1);
+        expect(parseResult.get(0)).to.be.instanceof(namespace.elements.Resource);
+
+        const resource = parseResult.get(0);
+        expect(resource.href.toValue()).to.equal('/{?categories*}');
+      });
+
       it('exposes multiple query parameter in href', () => {
         const path = new namespace.elements.Member('/', {
           parameters: [