feat(oas3): support example inside Parameter Object schema

Author: kylef

packages/openapi3-parser/CHANGELOG.md

@@ -4,8 +4,8 @@
 
 ### Enhancements
 
-- Minimal support for 'Parameter Object' schemas, simplest schemas using 'type'
-  are supported.
+- Minimal support for 'Parameter Object' schemas, simple schemas using 'type'
+  and 'example' are supported.
 
 ## 0.15.1 (2020-11-10)
 

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

@@ -19,14 +19,48 @@ const unsupportedKeys = [
   'properties', 'items', 'required', 'nullable', 'title', 'description',
   'default', 'oneOf', 'allOf', 'anyOf', 'not', 'additionalProperties',
   'format', 'discriminator', 'readOnly', 'writeOnly', 'xml', 'externalDocs',
-  'deprecated', 'example',
+  'deprecated',
 ];
 const isUnsupportedKey = R.anyPass(R.map(hasKey, unsupportedKeys));
 
-// purposely in the order defined in the JSON Schema spec, integer is an OAS 3 specific addition and thus is at the end
 const types = ['boolean', 'object', 'array', 'number', 'string', 'integer'];
 const isValidType = R.anyPass(R.map(hasValue, types));
 
+const typeToElementNameMap = {
+  array: 'array',
+  boolean: 'boolean',
+  integer: 'number',
+  null: 'null',
+  number: 'number',
+  object: 'object',
+  string: 'string',
+};
+
+// Returns whether the given element value matches the provided schema type
+const valueMatchesType = (type, value) => {
+  const expectedElementType = typeToElementNameMap[type];
+  return value.element === expectedElementType;
+};
+
+function validateValuesMatchSchema(context, schema) {
+  const validate = (member) => {
+    const type = schema.getValue('type');
+    if (type && !valueMatchesType(type, member.value)) {
+      return createWarning(context.namespace,
+        `'${name}' '${member.key.toValue()}' does not match expected type '${type}'`, member.value);
+    }
+
+    return member;
+  };
+
+  const parseMember = R.cond([
+    [hasKey('example'), validate],
+    [R.T, e => e],
+  ]);
+
+  return parseObject(context, name, parseMember)(schema);
+}
+
 /**
  * Parse Parameter Object's Schema Object
  *
@@ -53,6 +87,7 @@ function parseSchemaObject(context) {
 
   const parseMember = R.cond([
     [hasKey('type'), parseType],
+    [hasKey('example'), e => e.clone()],
 
     [isUnsupportedKey, createUnsupportedMemberWarning(namespace, name)],
     [isExtension, () => new namespace.elements.ParseResult()],
@@ -61,6 +96,7 @@ function parseSchemaObject(context) {
 
   return pipeParseResult(namespace,
     parseObject(context, name, parseMember, []),
+    R.curry(validateValuesMatchSchema)(context),
     (schema) => {
       const type = schema.getValue('type');
       let element;
@@ -76,7 +112,12 @@ function parseSchemaObject(context) {
       } else if (type === 'boolean') {
         element = new namespace.elements.Boolean();
       } else {
-        element = new namespace.elements.ParseResult([]);
+        return new namespace.elements.ParseResult([]);
+      }
+
+      const example = schema.get('example');
+      if (example) {
+        element.attributes.set('samples', [example]);
       }
 
       return element;

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

@@ -593,6 +593,43 @@ describe('Parameter Object', () => {
       expect(member.value).to.be.undefined;
     });
 
+    it('warns when example does not match expected type', () => {
+      const schema = new namespace.elements.Object({
+        name: 'example',
+        in: 'query',
+        schema: {
+          type: 'integer',
+          example: true,
+        },
+      });
+      const parseResult = parse(context, schema);
+
+      expect(parseResult.length).to.equal(2);
+      expect(parseResult).to.contain.warning(
+        "'Schema Object' 'example' does not match expected type 'integer'"
+      );
+    });
+
+    it('uses example with type as value', () => {
+      const parameter = new namespace.elements.Object({
+        name: 'example',
+        in: 'query',
+        schema: {
+          type: 'integer',
+          example: 2048,
+        },
+      });
+
+      const parseResult = parse(context, parameter);
+
+      expect(parseResult.length).to.equal(1);
+      const member = parseResult.get(0);
+      expect(member).to.be.instanceof(namespace.elements.Member);
+      expect(member.value).to.be.instanceof(namespace.elements.Number);
+      expect(member.value.content).to.be.undefined;
+      expect(member.value.attributes.get('samples').toValue()).to.deep.equal([2048]);
+    });
+
     it('provides a warning when schema is not an object', () => {
       const parameter = new namespace.elements.Object({
         name: 'example',