Merge commit 'cde5eb534a763791a6a77204bcfe3ded656c74f2' into releases

This commit is contained in:
RedocBot 2016-08-12 17:52:43 +00:00 committed by travis@localhost
commit 2fac0787b0
15 changed files with 209 additions and 100 deletions

View File

@ -11,6 +11,15 @@
## [Live demo](http://rebilly.github.io/ReDoc/)
## Features
- Extremely easy deployment
- Its 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

View File

@ -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>

View File

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

View File

@ -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;
}

View File

@ -1,82 +1,110 @@
<span *ngIf="schema.isFile" class="param-wrap">
<span class="param-type-file">file</span>
<div *ngIf="schema._produces && !isRequestSchema" class="file produces">
<ul>
<li *ngFor="let type of schema._produces">{{type}}</li>
</ul>
</div>
<div *ngIf="schema._consumes && isRequestSchema" class="file consume">
<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>
<ng-container [ngSwitch]="schema._widgetType">
<template ngSwitchCase="file">
<span class="param-wrap">
<span class="param-type-file">file</span>
<div *ngIf="schema._produces && !isRequestSchema" class="file produces">
<ul>
<li *ngFor="let type of schema._produces">{{type}}</li>
</ul>
</div>
</td>
</tr>
</table>
<div *ngIf="schema._consumes && isRequestSchema" class="file consume">
<ul>
<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>

View File

@ -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: " = ";
}
}

View File

@ -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 >');
});
});
});

View File

@ -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);
}

View File

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

View File

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

View File

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

View File

@ -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;

View File

@ -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
// ---------------------------

View File

@ -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 += ',';

View File

@ -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"