fix(oas3): gracefully handle non-string path keys

Author: kylef

packages/openapi3-parser/CHANGELOG.md

@@ -1,5 +1,12 @@
 # API Elements: OpenAPI 3 Parser Changelog
 
+## TBD
+
+### Bug Fixes
+
+- Return a parsing warning when Paths Object contains keys which are not
+  strings. Previously the parser would throw an error.
+
 ## 0.15.0 (2020-08-06)
 
 ### Enhancements

packages/openapi3-parser/lib/parser/oas/parsePathsObject.js

@@ -1,13 +1,16 @@
 const R = require('ramda');
-const { isObject, isExtension } = require('../../predicates');
-const { createError, createInvalidMemberWarning } = require('../annotations');
+const {
+  isObject, isString, isExtension, getKey,
+} = require('../../predicates');
+const { createError, createWarning } = require('../annotations');
 const pipeParseResult = require('../../pipeParseResult');
 const parsePathItemObject = require('./parsePathItemObject');
 
 const name = 'Paths Object';
 
-// Returns true if the member's key starts with a slash
-const isPathField = member => member.key.toValue().startsWith('/');
+// Returns true if the member's key is a string, and starts with a slash
+const isPathField = R.compose(R.both(isString, key => key.toValue().startsWith('/')), getKey);
+const isKeyString = R.compose(isString, getKey);
 
 /**
  * Parse Paths Object
@@ -19,6 +22,12 @@ function parsePaths(context, paths) {
   const { namespace } = context;
 
   const createParseResult = annotation => new namespace.elements.ParseResult([annotation]);
+  const createPathNotStringWarning = member => createWarning(namespace,
+    `'${name}' path must be a string, found ${member.key.element}`,
+    member.value);
+  const createKeyNotPathOrExtensionWarning = member => createWarning(namespace,
+    `'${name}' contains invalid key '${member.key.toValue()}', key must be a path starting with a leading forward slash '/', or an extension starting with 'x-'`,
+    member.value);
 
   const parseMember = R.cond([
     [isPathField, parsePathItemObject(context)],
@@ -27,7 +36,8 @@ function parsePaths(context, paths) {
     [isExtension, () => new namespace.elements.ParseResult()],
 
     // Return a warning for additional properties
-    [R.T, R.compose(createParseResult, createInvalidMemberWarning(namespace, name))],
+    [isKeyString, R.compose(createParseResult, createKeyNotPathOrExtensionWarning)],
+    [R.T, R.compose(createParseResult, createPathNotStringWarning)],
   ]);
 
   const parseMembers = object => R.chain(parseMember, new namespace.elements.ParseResult(object.content));

packages/openapi3-parser/test/integration/parser/oas/parseOpenAPI-test.js

@@ -35,7 +35,7 @@ describe('#parseOpenAPIObject', () => {
     expect(result.annotations.toValue()).to.deep.equal([
       "Version '3.1337.0' is not fully supported",
       "'Info Object' contains invalid key 'invalid'",
-      "'Paths Object' contains invalid key 'invalid'",
+      "'Paths Object' contains invalid key 'invalid', key must be a path starting with a leading forward slash '/', or an extension starting with 'x-'",
       "'Components Object' contains invalid key 'invalid'",
       "'OpenAPI Object' contains invalid key 'invalid'",
     ]);

packages/openapi3-parser/test/unit/parser/oas/parsePathsObject-test.js

@@ -28,6 +28,16 @@ describe('#parsePathsObject', () => {
     expect(parseResult.isEmpty).to.be.true;
   });
 
+  it('provides a warning when paths contains non-string field', () => {
+    const paths = new namespace.elements.Object();
+    paths.push(new namespace.elements.Member(true, {}));
+
+    const parseResult = parse(context, paths);
+
+    expect(parseResult.length).to.equal(1);
+    expect(parseResult).to.contain.warning("'Paths Object' path must be a string, found boolean");
+  });
+
   it('provides a warning when paths contains non-path field pattern', () => {
     const paths = new namespace.elements.Object({
       test: {},
@@ -36,7 +46,9 @@ describe('#parsePathsObject', () => {
     const parseResult = parse(context, paths);
 
     expect(parseResult.length).to.equal(1);
-    expect(parseResult).to.contain.warning("'Paths Object' contains invalid key 'test'");
+    expect(parseResult).to.contain.warning(
+      "'Paths Object' contains invalid key 'test', key must be a path starting with a leading forward slash '/', or an extension starting with 'x-'"
+    );
   });
 
   it('ignores extension objects', () => {