Merge pull request #227 from brendo/support-x-examples-request

Support x-examples vendor extension for requests

README.md

@@ -123,6 +123,7 @@ ReDoc makes use of the following [vendor extensions](http://swagger.io/specifica
 * [`x-logo`](docs/redoc-vendor-extensions.md#x-logo) - is used to specify API logo
 * [`x-traitTag`](docs/redoc-vendor-extensions.md#x-traitTag) - useful for handling out common things like Pagination, Rate-Limits, etc
 * [`x-code-samples`](docs/redoc-vendor-extensions.md#x-code-samples) - specify operation code samples
+* [`x-examples`](docs/redoc-vendor-extensions.md#x-examples) - specify JSON example for requests
 * [`x-nullable`](docs/redoc-vendor-extensions.md#nullable) - mark schema param as a nullable
 * [`x-displayName`](docs/redoc-vendor-extensions.md#x-displayname) - specify human-friendly names for the menu categories
 * [`x-tagGroups`](docs/redoc-vendor-extensions.md#x-tagGroups) - group tags by categories in the side menu

docs/redoc-vendor-extensions.md

@@ -169,6 +169,17 @@ lang: JavaScript
 source: console.log('Hello World');
 ```
 
+### Parameter Object vendor extensions
+Extends OpenAPI [Parameter Object](http://swagger.io/specification/#parameterObject)
+#### x-examples
+| Field Name     |  Type    | Description |
+| :------------- | :------: | :---------- |
+| x-examples | [Example Object](http://swagger.io/specification/#exampleObject)  | Object that contains examples for the request. Applies when `in` is `body` and mime-type is `application/json` |
+
+###### Usage in ReDoc
+`x-examples` are rendered in the JSON tab on the right panel of ReDoc.
+
+
 ### Schema Object vendor extensions
 Extends OpenAPI [Schema Object](http://swagger.io/specification/#schemaObject)
 #### x-nullable

lib/components/ResponsesSamples/responses-samples.ts

@@ -3,7 +3,7 @@
 import { Component, Input, OnInit, ChangeDetectionStrategy } from '@angular/core';
 import { BaseComponent, SpecManager } from '../base';
 import JsonPointer from '../../utils/JsonPointer';
-import { statusCodeType } from '../../utils/helpers';
+import { statusCodeType, getJsonLike } from '../../utils/helpers';
 
 
 function isNumeric(n) {
@@ -11,7 +11,7 @@ function isNumeric(n) {
 }
 
 function hasExample(response) {
-  return ((response.examples && response.examples['application/json']) ||
+  return ((response.examples && getJsonLike(response.examples)) ||
     response.schema);
 }
 

lib/components/SchemaSample/schema-sample.ts

@@ -3,9 +3,10 @@
 import { Component, ElementRef, Input, ChangeDetectionStrategy, OnInit } from '@angular/core';
 
 import * as OpenAPISampler from 'openapi-sampler';
-
+import JsonPointer from '../../utils/JsonPointer';
 import { BaseComponent, SpecManager } from '../base';
 import { SchemaNormalizer } from '../../services/schema-normalizer.service';
+import { getJsonLike } from '../../utils/helpers';
 
 @Component({
   selector: 'schema-sample',
@@ -42,8 +43,16 @@ export class SchemaSample extends BaseComponent implements OnInit {
       this.pointer += '/schema';
     }
 
-    if (base.examples && base.examples['application/json']) {
-      sample = base.examples['application/json'];
+    // Support x-examples, allowing requests to specify an example.
+    let examplePointer:string = JsonPointer.join(JsonPointer.dirName(this.pointer), 'x-examples');
+    let requestExamples:any = this.specMgr.byPointer(examplePointer);
+    if (requestExamples) {
+      base.examples = requestExamples;
+    }
+
+    let jsonLikeSample = base.examples && getJsonLike(base.examples);
+    if (jsonLikeSample) {
+      sample = jsonLikeSample;
     } else {
       let selectedDescendant;
 

lib/utils/helpers.ts

@@ -114,3 +114,17 @@ export function snapshot(obj) {
 
   return temp;
 }
+
+export function isJsonLike(contentType: string): boolean {
+  return contentType.search(/json/i) !== -1;
+}
+
+export function getJsonLike(object: object) {
+  const jsonLikeKeys = Object.keys(object).filter(isJsonLike);
+
+  if (!jsonLikeKeys.length) {
+    return false;
+  }
+
+  return object[jsonLikeKeys.shift()];
+}

tests/unit/helpers.spec.ts

@@ -1,6 +1,7 @@
 'use strict';
 
-import {statusCodeType} from '../../lib/utils/helpers';
+import {statusCodeType, isJsonLike, getJsonLike } from '../../lib/utils/helpers';
+
 describe('Utils', () => {
   describe('statusCodeType', () => {
     it('Should return info for status codes within 100 and 200', ()=> {
@@ -30,4 +31,34 @@ describe('Utils', () => {
       (() => statusCodeType(600)).should.throw('invalid HTTP code');
     });
   });
+
+  describe('isJsonLike', () => {
+    it('Should return true for a string that contains `json`', () => {
+      isJsonLike('application/json').should.be.equal(true);
+    });
+    it('Should return false for a string that does not contain `json`', () => {
+      isJsonLike('application/xml').should.be.equal(false);
+    });
+  });
+
+  describe('getJsonLike', () => {
+    it('Should return a value when a JSON-like key exists', () => {
+      const examples = {
+        "application/vnd.api+json": {
+          "message": "Hello World"
+        },
+        "application/xml": "<message>Hello World</message>"
+      };
+
+      (getJsonLike(examples).message).should.be.equal("Hello World");
+    });
+
+    it('Should return undefined when no JSON-like key exists', () => {
+      const examples = {
+        "application/xml": "<message>Hello World</message>"
+      };
+
+      getJsonLike(examples).should.be.equal(false);
+    });
+  })
 });