Merge commit 'cde5eb534a763791a6a77204bcfe3ded656c74f2' into releases

README.md

@@ -11,6 +11,15 @@
 
 ## [Live demo](http://rebilly.github.io/ReDoc/)
 
+## Features
+- Extremely easy deployment
+- It’s free and open-source project under MIT license
+- The widest OpenAPI features support (yes, it supports even discriminator)
+- Neat documentation for nested objects
+- Code samples support (via vendor extension)
+- Responsive three-panel design with menu/scrolling synchronization
+- Integrate API introduction into side menu - ReDoc takes advantage of markdown headings from OpenAPI description field. It pulls them into side menu and also supports deep linking.
+
 ## Roadmap
   - [ ] docs pre-rendering (performance and SEO)
   - [ ] ability to simple customization
@@ -90,7 +99,7 @@ ReDoc makes use of the following [vendor extensions](http://swagger.io/specifica
 * [`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
 
-### Options
+### `<redoc>` tag attributes
 * `spec-url` - relative or absolute url to your spec file;
 * `scroll-y-offset` - If set, specifies a vertical scroll-offset. This is often useful when there are fixed positioned elements at the top of the page, such as navbars, headers etc;
 `scroll-y-offset` can be specified in various ways:
@@ -105,7 +114,7 @@ Instead of adding `spec-url` attribute to the `<redoc>` element you can initiali
 Redoc.init(specUrl, options)
 ```
 
-`options` is javascript object with camel-cased version of options names as the keys, e.g.:
+`options` is javascript object with camel-cased version of `<redoc>` tag attribute names as the keys, e.g.:
 ```js
 Redoc.init('http://petstore.swagger.io/v2/swagger.json', {
   scrollYOffset: 50

demo/index.html

@@ -26,5 +26,14 @@
 
     <script src="main.js"> </script>
     <script src="./dist/redoc.min.js"> </script>
+    <script>
+      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+      })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
+
+      ga('create', 'UA-81703547-1', 'auto');
+      ga('send', 'pageview');
+    </script>
   </body>
 </html>

lib/components/ApiInfo/api-info.scss

@@ -8,6 +8,10 @@
   width: 60%;
   padding: 40px;
   box-sizing: border-box;
+
+  @media (max-width: $right-panel-squash-breakpoint) {
+    width: 100%;
+  }
 }
 
 a.openapi-button {

lib/components/JsonSchema/json-schema-common.scss

@@ -77,6 +77,12 @@ $sub-schema-offset: ($bullet-size / 2) + $bullet-margin;
   font-weight: $base-font-weight;
 }
 
+.param-type.tuple:before {
+  content: "Tuple";
+  color: $black;
+  font-weight: $base-font-weight;
+}
+
 .param-type.with-hint {
   display: inline-block;
   margin-bottom: 0.4em;
@@ -86,7 +92,6 @@ $sub-schema-offset: ($bullet-size / 2) + $bullet-margin;
 }
 
 .param-type-trivial {
-  margin: 10px 10px 0;
   display: inline-block;
 }
 

lib/components/JsonSchema/json-schema.html

@@ -1,82 +1,110 @@
-<span *ngIf="schema.isFile" class="param-wrap">
+<ng-container [ngSwitch]="schema._widgetType">
-  <span class="param-type-file">file</span>
+  <template ngSwitchCase="file">
-  <div *ngIf="schema._produces && !isRequestSchema" class="file produces">
+    <span class="param-wrap">
-    <ul>
+      <span class="param-type-file">file</span>
-      <li *ngFor="let type of schema._produces">{{type}}</li>
+      <div *ngIf="schema._produces && !isRequestSchema" class="file produces">
-    </ul>
+        <ul>
-  </div>
+          <li *ngFor="let type of schema._produces">{{type}}</li>
-  <div *ngIf="schema._consumes && isRequestSchema" class="file consume">
+        </ul>
-    <ul>
-      <li *ngFor="let type of schema._consumes">{{type}}</li>
-    </ul>
-  </div>
-</span>
-<span *ngIf="schema.isTrivial && !schema.isFile" class="param-wrap">
-  <span class="param-type param-type-trivial {{schema.type}}"
-    [ngClass]="{'with-hint': schema._displayTypeHint}"
-    title="{{schema._displayTypeHint}}">{{schema._displayType}} {{schema._displayFormat}}
-    <span class="param-range" *ngIf="schema._range"> {{schema._range}} </span>
-  </span>
-  <div *ngIf="schema.enum" class="param-enum">
-    <span *ngFor="let enumItem of schema.enum" class="enum-value {{enumItem.type}}"> {{enumItem.val | json}} </span>
-  </div>
-</span>
-<table *ngIf="!schema.isTrivial" class="params-wrap" [ngClass]="{'params-array': _isArray}">
-  <!-- <caption> {{_displayType}} </caption> -->
-  <template ngFor [ngForOf]="properties" let-prop="$implicit" let-last="last" [ngForTrackBy]="trackByIdx">
-    <tr class="param" [ngClass]="{'last': last,
-        'discriminator': prop.isDiscriminator && !activeDescendant.empty,
-        'complex': prop._pointer,
-        'additional': prop._additional,
-        'expanded': subSchema.visible
-      }">
-      <td class="param-name">
-        <span class="param-name-wrap" (click)="subSchema.toggle()">
-          <span class="param-name-content" >{{prop._name}}</span>
-          <svg *ngIf="prop._pointer" xmlns="http://www.w3.org/2000/svg" version="1.1" x="0" y="0" viewBox="0 0 24 24" xml:space="preserve">
-            <polygon points="17.3 8.3 12 13.6 6.7 8.3 5.3 9.7 12 16.4 18.7 9.7 "/>
-          </svg>
-        </span>
-      </td>
-      <td class="param-info">
-        <div>
-          <span class="param-type {{prop.type}}" [ngClass]="{'with-hint': prop._displayTypeHint}"
-          title="{{prop._displayTypeHint}}"> {{prop._displayType}} {{prop._displayFormat}}
-          <span class="param-range" *ngIf="prop._range"> {{prop._range}} </span>
-          </span>
-          <span *ngIf="prop._required" class="param-required">Required</span>
-          <div *ngIf="prop.default">Default: {{prop.default | json}}</div>
-          <div *ngIf="prop.enum && !prop.isDiscriminator" class="param-enum">
-            <span *ngFor="let enumItem of prop.enum" class="enum-value {{enumItem.type}}"> {{enumItem.val | json}} </span>
-          </div>
-        </div>
-        <div class="param-description" [innerHtml]="prop.description | marked"></div>
-        <div class="discriminator-info" *ngIf="prop.isDiscriminator">
-          <span>This field value determines the exact schema:</span>
-          <drop-down (change)="selectDescendant($event)">
-            <option *ngFor="let descendant of schema._descendants; let i=index"
-            [value]="i">{{descendant.name}}</option>
-          </drop-down>
-        </div>
-      </td>
-    </tr>
-    <tr class="param-schema" [ngClass]="{'param-array': prop._isArray, 'last': last}" [hidden]="!prop._pointer">
-      <td colspan="2">
-        <zippy #subSchema title="Expand" [headless]="true" (open)="lazySchema.load()" [visible]="autoExpand">
-          <json-schema-lazy #lazySchema [auto]="autoExpand" class="nested-schema" [pointer]="prop._pointer" [isArray]='prop._isArray'
-          [nestOdd]="!nestOdd" [isRequestSchema]="isRequestSchema">
-          </json-schema-lazy>
-        </zippy>
-      </td>
-    </tr>
-  </template>
-  <tr *ngIf="hasDescendants" class="param-wrap discriminator-wrap" [ngClass]="{empty:activeDescendant.empty}">
-    <td colspan="2">
-      <div class="derived-schema" *ngFor="let descendant of schema._descendants" [ngClass]="{active: descendant.active, empty: descendant.empty}">
-        <json-schema class="discriminator-part" *ngIf="!descendant.empty" [childFor]="pointer"
-        pointer="{{descendant.$ref}}" [final]="descendant.final" [isRequestSchema]="isRequestSchema">
-        </json-schema>
       </div>
-    </td>
+      <div *ngIf="schema._consumes && isRequestSchema" class="file consume">
-  </tr>
+        <ul>
-</table>
+          <li *ngFor="let type of schema._consumes">{{type}}</li>
+        </ul>
+      </div>
+    </span>
+  </template>
+  <template ngSwitchCase="trivial">
+    <span class="param-wrap">
+      <span class="param-type param-type-trivial {{schema.type}}"
+        [ngClass]="{'with-hint': schema._displayTypeHint}"
+        title="{{schema._displayTypeHint}}">{{schema._displayType}} {{schema._displayFormat}}
+        <span class="param-range" *ngIf="schema._range"> {{schema._range}} </span>
+      </span>
+      <div *ngIf="schema.enum" class="param-enum">
+        <span *ngFor="let enumItem of schema.enum" class="enum-value {{enumItem.type}}"> {{enumItem.val | json}} </span>
+      </div>
+    </span>
+  </template>
+  <template ngSwitchCase="tuple">
+    <div class="params-wrap params-array array-tuple">
+      <template ngFor [ngForOf]="schema.items" let-item="$implicit" let-idx="index" [ngForTrackBy]="trackByIdx">
+        <div class="tuple-item">
+          <span class="tuple-item-index"> [{{idx}}]: </span>
+          <json-schema class="nested-schema" [pointer]="item._pointer"
+          [nestOdd]="!nestOdd" [isRequestSchema]="isRequestSchema">
+          </json-schema>
+        </div>
+      </template>
+    </div>
+  </template>
+  <template ngSwitchCase="array">
+    <json-schema class="nested-schema" [pointer]="schema._pointer" [isArray]='true'
+    [nestOdd]="!nestOdd" [isRequestSchema]="isRequestSchema"> </json-schema>
+  </template>
+  <template ngSwitchCase="object">
+    <table class="params-wrap" [ngClass]="{'params-array': schema._isArray}">
+      <!-- <caption> {{_displayType}} </caption> -->
+      <template ngFor [ngForOf]="properties" let-prop="$implicit" let-last="last" [ngForTrackBy]="trackByIdx">
+        <tr class="param" [ngClass]="{'last': last,
+            'discriminator': prop.isDiscriminator && !activeDescendant.empty,
+            'complex': prop._pointer,
+            'additional': prop._additional,
+            'expanded': subSchema.visible
+          }">
+          <td class="param-name">
+            <span class="param-name-wrap" (click)="subSchema.toggle()">
+              <span class="param-name-content">
+                {{prop._name}}
+                <span class="param-enum-value" [hidden]="!prop._enumItem"> {{prop._enumItem?.val | json}} </span>
+              </span>
+              <svg *ngIf="prop._pointer" xmlns="http://www.w3.org/2000/svg" version="1.1" x="0" y="0" viewBox="0 0 24 24" xml:space="preserve">
+                <polygon points="17.3 8.3 12 13.6 6.7 8.3 5.3 9.7 12 16.4 18.7 9.7 "/>
+              </svg>
+            </span>
+          </td>
+          <td class="param-info">
+            <div>
+              <span class="param-type {{prop.type}}" [ngClass]="{'with-hint': prop._displayTypeHint, 'tuple': prop._isTuple}"
+              title="{{prop._displayTypeHint}}"> {{prop._displayType}} {{prop._displayFormat}}
+              <span class="param-range" *ngIf="prop._range"> {{prop._range}} </span>
+              </span>
+              <span *ngIf="prop._required" class="param-required">Required</span>
+              <div *ngIf="prop.default">Default: {{prop.default | json}}</div>
+              <div *ngIf="prop.enum && !prop.isDiscriminator" class="param-enum">
+                <span *ngFor="let enumItem of prop.enum" class="enum-value {{enumItem.type}}"> {{enumItem.val | json}} </span>
+              </div>
+            </div>
+            <div class="param-description" [innerHtml]="prop.description | marked"></div>
+            <div class="discriminator-info" *ngIf="prop.isDiscriminator">
+              <span>This field value determines the exact schema:</span>
+              <drop-down (change)="selectDescendant($event)">
+                <option *ngFor="let descendant of schema._descendants; let i=index"
+                [value]="i">{{descendant.name}}</option>
+              </drop-down>
+            </div>
+          </td>
+        </tr>
+        <tr class="param-schema" [ngClass]="{'last': last}" [hidden]="!prop._pointer">
+          <td colspan="2">
+            <zippy #subSchema title="Expand" [headless]="true" (open)="lazySchema.load()" [visible]="autoExpand">
+              <json-schema-lazy #lazySchema [auto]="autoExpand" class="nested-schema" [pointer]="prop._pointer"
+              [nestOdd]="!nestOdd" [isRequestSchema]="isRequestSchema">
+              </json-schema-lazy>
+            </zippy>
+          </td>
+        </tr>
+      </template>
+      <tr *ngIf="hasDescendants" class="param-wrap discriminator-wrap" [ngClass]="{empty:activeDescendant.empty}">
+        <td colspan="2">
+          <div class="derived-schema" *ngFor="let descendant of schema._descendants" [ngClass]="{active: descendant.active, empty: descendant.empty}">
+            <json-schema class="discriminator-part" *ngIf="!descendant.empty" [childFor]="pointer" [nestOdd]="nestOdd"
+            pointer="{{descendant.$ref}}" [final]="descendant.final" [isRequestSchema]="isRequestSchema">
+            </json-schema>
+          </div>
+        </td>
+      </tr>
+    </table>
+  </template>
+
+</ng-container>

lib/components/JsonSchema/json-schema.scss

@@ -58,11 +58,13 @@ $array-marker-line-height: 1.5;
     border-top-color: white;
   }
 
-  > .params-wrap > .param:first-of-type > .param-name:before, > .params-wrap > .param:last-of-type > .param-name:after {
+  > .params-wrap > .param:first-of-type > .param-name:before,
+  > .params-wrap > .param:last-of-type > .param-name:after {
     border-color: $side-menu-active-bg-color;
   }
 
-  > .params-wrap > .param:last-of-type, > .params-wrap > .param.last {
+  > .params-wrap > .param:last-of-type,
+  > .params-wrap > .param.last {
     > .param-name:after {
       border-color: $side-menu-active-bg-color;
     }
@@ -119,11 +121,13 @@ table {
 
 .params-wrap.params-array:after {
   content: "]";
+  font-family: monospace;
 }
 
 .params-wrap.params-array:before {
   content: "Array [";
   padding-top: 1em;
+  font-family: monospace;
 }
 
 .params-wrap.params-array {
@@ -201,3 +205,30 @@ li:before {
   content: "- ";
   font-weight: bold;
 }
+
+.array-tuple > .tuple-item {
+  margin-top: 1.5em;
+  display: flex;
+
+  > span {
+    flex: 0;
+    padding: 10px 15px 10px 0;
+    font-family: monospace;
+  }
+
+  > json-schema {
+    flex: 1;
+    &:before, &:after {
+      display: none;
+    }
+  }
+}
+
+.param-enum-value {
+  padding: 2px;
+  background-color: #e6ebf6;
+
+  &:before {
+    content: " = ";
+  }
+}

lib/components/JsonSchema/json-schema.spec.ts

@@ -44,13 +44,13 @@ describe('Redoc components', () => {
       component.schema.isTrivial.should.be.true();
     });
 
-    it('should use < * > notation for prop without type', () => {
+    it('should use < anything > notation for prop without type', () => {
       component.pointer = '#';
       (<any>specMgr)._schema = {type: 'object', properties: {
         test: {}
       }};
       fixture.detectChanges();
-      component.schema._properties[0]._displayType.should.be.equal('< * >');
+      component.schema._properties[0]._displayType.should.be.equal('< anything >');
     });
   });
 });

lib/components/JsonSchema/json-schema.ts

@@ -22,7 +22,6 @@ export class JsonSchema extends BaseComponent {
   _hasSubSchemas: boolean = false;
   properties: any;
   _isArray: boolean;
-  @Input() isArray: boolean;
   @Input() final: boolean = false;
   @Input() nestOdd: boolean;
   @Input() childFor: string;
@@ -89,7 +88,6 @@ export class JsonSchema extends BaseComponent {
     }
 
     this.properties = this.schema._properties;
-    this._isArray = this.isArray || this.schema._isArray;
     if (this.isRequestSchema) {
       this.properties = this.properties && this.properties.filter(prop => !prop.readOnly);
     }

lib/components/Method/method.scss

@@ -142,7 +142,7 @@ responses-samples {
   cursor: pointer;
 }
 
-@media (max-width: 1100px) {
+@media (max-width: $right-panel-squash-breakpoint) {
   .methods:before {
     display: none;
   }

lib/components/MethodsList/methods-list.scss

@@ -6,7 +6,7 @@
   background-color: white;
   width: 60%;
 
-  @media (max-width: 1100px) {
+  @media (max-width: $right-panel-squash-breakpoint) {
     width: 100%;
   }
 }

lib/components/Redoc/redoc.scss

@@ -94,7 +94,7 @@ api-logo {
 }
 
 
-@media (max-width: 1100px) {
+@media (max-width: $right-panel-squash-breakpoint) {
   #api-content:before {
     display: none;
   }

lib/services/schema-helper.service.ts

@@ -49,6 +49,10 @@ const injectors = {
         injectTo.enum = propertySchema.enum.map((value) => {
           return {val: value, type: typeof value};
         });
+        if (propertySchema.enum && propertySchema.enum.length === 1) {
+          injectTo._enumItem = propertySchema.enum[0];
+          injectTo.enum = null;
+        }
       }
     }
   },
@@ -59,9 +63,9 @@ const injectors = {
       injectTo.discriminator = propertySchema.discriminator;
     }
   },
-  array: {
+  simpleArray: {
     check: (propertySchema) => {
-      return propertySchema.type === 'array';
+      return propertySchema.type === 'array' && !Array.isArray(propertySchema.items);
     },
     inject: (injectTo, propertySchema = injectTo, propPointer) => {
       injectTo._isArray = true;
@@ -69,6 +73,23 @@ const injectors = {
         || JsonPointer.join(propertySchema._pointer || propPointer, ['items']);
 
       SchemaHelper.runInjectors(injectTo, propertySchema.items, propPointer);
+      injectTo._widgetType = 'array';
+    }
+  },
+  tuple: {
+    check: (propertySchema) => {
+      return propertySchema.type === 'array' && Array.isArray(propertySchema.items);
+    },
+    inject: (injectTo, propertySchema = injectTo, propPointer) => {
+      injectTo._isTuple = true;
+      injectTo._displayType = '';
+      let itemsPtr = JsonPointer.join(propertySchema._pointer || propPointer, ['items']);
+      for (let i=0; i < propertySchema.items.length; i++) {
+        let itemSchema = propertySchema.items[i];
+        itemSchema._pointer = itemSchema._pointer || JsonPointer.join(itemsPtr, [i.toString()]);
+      }
+      injectTo._widgetType = 'tuple';
+      // SchemaHelper.runInjectors(injectTo, propertySchema.items, propPointer);
     }
   },
   object: {
@@ -78,14 +99,16 @@ const injectors = {
     inject: (injectTo, propertySchema = injectTo) => {
       let baseName = propertySchema._pointer && JsonPointer.baseName(propertySchema._pointer);
       injectTo._displayType = propertySchema.title || baseName || 'object';
+      injectTo._widgetType = 'object';
     }
   },
   noType: {
     check: (propertySchema) => !propertySchema.type,
     inject: (injectTo) => {
-      injectTo._displayType = '< * >';
+      injectTo._displayType = '< anything >';
       injectTo._displayTypeHint = 'This field may contain data of any type';
       injectTo.isTrivial = true;
+      injectTo._widgetType = 'trivial';
     }
   },
   simpleType: {
@@ -103,6 +126,7 @@ const injectors = {
         injectTo._displayType = propertySchema.title ?
           `${propertySchema.title} (${propertySchema.type})` : propertySchema.type;
       }
+      injectTo._widgetType = 'trivial';
     }
   },
   integer: {
@@ -160,7 +184,7 @@ const injectors = {
       let root = SpecManager.instance().schema;
       injectTo._produces = parentParam && parentParam.produces || root.produces;
       injectTo._consumes = parentParam && parentParam.consumes || root.consumes;
-
+      injectTo._widgetType = 'file';
     }
   }
 };
@@ -240,7 +264,7 @@ export class SchemaHelper {
 
   static unwrapArray(schema, pointer) {
     var res = schema;
-    if (schema && schema.type === 'array') {
+    if (schema && schema.type === 'array' && !Array.isArray(schema.items)) {
       let ptr = schema.items._pointer || JsonPointer.join(pointer, ['items']);
       res = schema.items;
       res._isArray = true;

lib/shared/styles/_variables.scss

@@ -57,6 +57,7 @@ $sample-panel-color: lighten($black, 80%);
 $tree-lines-color: rgba($primary-color, .5);
 
 $side-menu-mobile-breakpoint: 1000px;
+$right-panel-squash-breakpoint: 1100px;
 
 // Border Radius
 // ---------------------------

lib/utils/JsonFormatterPipe.ts

@@ -82,7 +82,7 @@ function objectToHTML(json) {
     key = keys[i];
     hasContents = true;
     output += '<li><div class="hoverable ' + collapsed + '">';
-    output += '<span class="property">' + htmlEncode(key) + '</span>: ';
+    output += '<span class="property">\"' + htmlEncode(key) + '"</span>: ';
     output += valueToHTML(json[key]);
     if (i < length - 1) {
       output += ',';

package.json

@@ -1,7 +1,7 @@
 {
   "name": "redoc",
   "description": "Swagger-generated API Reference Documentation",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "repository": {
     "type": "git",
     "url": "git://github.com/Rebilly/ReDoc"