From e72471feab705240daec5ce5634c51aa245853aa Mon Sep 17 00:00:00 2001 From: Brendan Abbott Date: Mon, 6 Mar 2017 17:54:52 +1000 Subject: [PATCH 01/18] Allow JSON-like examples to be shown, which supports things like JSON API --- .../ResponsesSamples/responses-samples.ts | 4 +-- lib/components/SchemaSample/schema-sample.ts | 6 ++-- lib/utils/helpers.ts | 14 ++++++++ tests/unit/helpers.spec.ts | 33 ++++++++++++++++++- 4 files changed, 52 insertions(+), 5 deletions(-) diff --git a/lib/components/ResponsesSamples/responses-samples.ts b/lib/components/ResponsesSamples/responses-samples.ts index 9e6a436b..6e076adb 100644 --- a/lib/components/ResponsesSamples/responses-samples.ts +++ b/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); } diff --git a/lib/components/SchemaSample/schema-sample.ts b/lib/components/SchemaSample/schema-sample.ts index 79a533d2..b458b24a 100644 --- a/lib/components/SchemaSample/schema-sample.ts +++ b/lib/components/SchemaSample/schema-sample.ts @@ -6,6 +6,7 @@ import * as OpenAPISampler from 'openapi-sampler'; import { BaseComponent, SpecManager } from '../base'; import { SchemaNormalizer } from '../../services/schema-normalizer.service'; +import { getJsonLike } from '../../utils/helpers'; @Component({ selector: 'schema-sample', @@ -42,8 +43,9 @@ export class SchemaSample extends BaseComponent implements OnInit { this.pointer += '/schema'; } - if (base.examples && base.examples['application/json']) { - sample = base.examples['application/json']; + let jsonLikeSample = base.examples && getJsonLike(base.examples); + if (jsonLikeSample) { + sample = jsonLikeSample; } else { let selectedDescendant; diff --git a/lib/utils/helpers.ts b/lib/utils/helpers.ts index 86fcc839..2ca43626 100644 --- a/lib/utils/helpers.ts +++ b/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()]; +} diff --git a/tests/unit/helpers.spec.ts b/tests/unit/helpers.spec.ts index ac577bb5..3cba8224 100644 --- a/tests/unit/helpers.spec.ts +++ b/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": "Hello World" + }; + + (getJsonLike(examples).message).should.be.equal("Hello World"); + }); + + it('Should return undefined when no JSON-like key exists', () => { + const examples = { + "application/xml": "Hello World" + }; + + getJsonLike(examples).should.be.equal(false); + }); + }) }); From 3c569cde6e64c463f901b39c4e121ee47dfa5046 Mon Sep 17 00:00:00 2001 From: Brendan Abbott Date: Thu, 9 Mar 2017 20:55:23 +1000 Subject: [PATCH 02/18] Support x-examples vendor extension for requests --- README.md | 1 + docs/redoc-vendor-extensions.md | 11 +++++++++++ lib/components/SchemaSample/schema-sample.ts | 9 ++++++++- 3 files changed, 20 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 350f7b1d..8446cc91 100644 --- a/README.md +++ b/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 diff --git a/docs/redoc-vendor-extensions.md b/docs/redoc-vendor-extensions.md index 2e6329cc..b285aafb 100644 --- a/docs/redoc-vendor-extensions.md +++ b/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 diff --git a/lib/components/SchemaSample/schema-sample.ts b/lib/components/SchemaSample/schema-sample.ts index 79a533d2..1f046727 100644 --- a/lib/components/SchemaSample/schema-sample.ts +++ b/lib/components/SchemaSample/schema-sample.ts @@ -3,7 +3,7 @@ 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'; @@ -42,6 +42,13 @@ export class SchemaSample extends BaseComponent implements OnInit { this.pointer += '/schema'; } + // 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; + } + if (base.examples && base.examples['application/json']) { sample = base.examples['application/json']; } else { From 7106838bb4045d5e1ebf5beb5bc407ce561aa0ae Mon Sep 17 00:00:00 2001 From: Roman Hotsiy Date: Fri, 10 Mar 2017 01:06:40 +0200 Subject: [PATCH 03/18] =?UTF-8?q?chore:=20update=20changelog=20?= =?UTF-8?q?=F0=9F=97=9E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [skip ci] --- CHANGELOG.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 02c7fbff..b8e2d112 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,30 @@ + +# 1.11.0 (2017-03-09) + + +### Bug Fixes + +* do not hang when swagger doesn't contain any paths ([e4f5388](https://github.com/Rebilly/ReDoc/commit/e4f5388)), closes [#216](https://github.com/Rebilly/ReDoc/issues/216) +[#201](https://github.com/Rebilly/ReDoc/issues/201) +* optimize and support inherited discriminator ([64e5741](https://github.com/Rebilly/ReDoc/commit/64e5741)) +* redoc hangs when indexing recursive discriminator-based definitions ([1e96f88](https://github.com/Rebilly/ReDoc/commit/1e96f88)) +* wrong warnings for $ref not single ([193f4bf](https://github.com/Rebilly/ReDoc/commit/193f4bf)), closes [#221](https://github.com/Rebilly/ReDoc/issues/221) +* x-extendedDiscriminator not working ([4899f3e](https://github.com/Rebilly/ReDoc/commit/4899f3e)), closes [#217](https://github.com/Rebilly/ReDoc/issues/217) + + +### Features + +* copy pretty-printed JSON ([e99d66d](https://github.com/Rebilly/ReDoc/commit/e99d66d)), closes [#219](https://github.com/Rebilly/ReDoc/issues/219) +* support for OpenAPI object as a parameter for `init` ([d99f256](https://github.com/Rebilly/ReDoc/commit/d99f256)), closes [#224](https://github.com/Rebilly/ReDoc/issues/224) + + +## 1.10.2 (2017-03-01) + +### Bug Fixes +* clear page fragment when scroll to the beginning +* update docs for x-tagGroup, add warning [#215](https://github.com/Rebilly/ReDoc/issues/215) +* show warning for non-used in tagGroup tags + ## 1.10.1 (2017-02-27) From bed15dddc607a7952324367e266b789e4a91d966 Mon Sep 17 00:00:00 2001 From: Roman Hotsiy Date: Wed, 15 Mar 2017 17:50:10 +0200 Subject: [PATCH 04/18] chore: upgrade to angular 4.x --- lib/app.module.ts | 3 +- lib/components/JsonSchema/json-schema.html | 28 +++---- lib/components/ParamsList/params-list.html | 4 +- lib/components/Search/redoc-search.html | 2 +- .../security-definitions.html | 8 +- lib/index.ts | 2 +- lib/redoc.module.ts | 1 + lib/services/content-projector.service.ts | 12 +-- lib/services/schema-normalizer.service.ts | 1 - lib/utils/md-renderer.ts | 1 - package.json | 74 +++++++++---------- 11 files changed, 69 insertions(+), 67 deletions(-) diff --git a/lib/app.module.ts b/lib/app.module.ts index 37ee2c5a..5892f23c 100644 --- a/lib/app.module.ts +++ b/lib/app.module.ts @@ -1,11 +1,12 @@ import { NgModule } from '@angular/core'; import { BrowserModule } from '@angular/platform-browser'; +import { BrowserAnimationsModule } from '@angular/platform-browser/animations'; import { RedocModule } from './redoc.module'; import { Redoc } from './components/index'; @NgModule({ - imports: [ BrowserModule, RedocModule ], + imports: [ BrowserModule, BrowserAnimationsModule, RedocModule ], bootstrap: [ Redoc ], exports: [ Redoc ] }) diff --git a/lib/components/JsonSchema/json-schema.html b/lib/components/JsonSchema/json-schema.html index c60b7a28..8ab87420 100644 --- a/lib/components/JsonSchema/json-schema.html +++ b/lib/components/JsonSchema/json-schema.html @@ -1,5 +1,5 @@ - - - - -