From 1ccab589f857363be5b9eb21f00d06757e4114c7 Mon Sep 17 00:00:00 2001 From: Sean Kennedy Date: Fri, 20 Nov 2015 15:11:15 -0500 Subject: [PATCH] implement option to control whether models are displayed as valid JSON schema or the docs rendering (with descriptions) by default --- README.md | 1 + src/main/html/index.html | 1 + src/main/javascript/SwaggerUi.js | 7 ++++++- src/main/javascript/view/OperationView.js | 15 +++++++++++---- src/main/javascript/view/ParameterView.js | 3 ++- src/main/javascript/view/SignatureView.js | 8 ++++++-- src/main/javascript/view/StatusCodeView.js | 1 + 7 files changed, 28 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 044b96cc..f9a30213 100644 --- a/README.md +++ b/README.md @@ -98,6 +98,7 @@ booleanValues | SwaggerUI renders boolean data types as a dropdown. By default i docExpansion | Controls how the API listing is displayed. It can be set to 'none' (default), 'list' (shows operations for each resource), or 'full' (fully expanded: shows operations and their details). apisSorter | Apply a sort to the API/tags list. It can be 'alpha' (sort by name) or a function (see Array.prototype.sort() to know how sort function works). Default is the order returned by the server unchanged. operationsSorter | Apply a sort to the operation list of each API. It can be 'alpha' (sort by paths alphanumerically), 'method' (sort by HTTP method) or a function (see Array.prototype.sort() to know how sort function works). Default is the order returned by the server unchanged. +defaultModelRendering | Controls how models are shown when the API is first rendered. (The user can always switch the rendering for a given model by clicking the 'Model' and 'Model Schema' links.) It can be set to 'model' or 'schema', and the default is 'schema'. onComplete | This is a callback function parameter which can be passed to be notified of when SwaggerUI has completed rendering successfully. onFailure | This is a callback function parameter which can be passed to be notified of when SwaggerUI encountered a failure was unable to render. highlightSizeThreshold | Any size response below this threshold will be highlighted syntactically, attempting to highlight large responses can lead to browser hangs, not including a threshold will default to highlight all returned responses. diff --git a/src/main/html/index.html b/src/main/html/index.html index 7442d3f1..20e6afc1 100644 --- a/src/main/html/index.html +++ b/src/main/html/index.html @@ -70,6 +70,7 @@ }, docExpansion: "none", apisSorter: "alpha", + defaultModelRendering: 'schema', showRequestHeaders: false }); diff --git a/src/main/javascript/SwaggerUi.js b/src/main/javascript/SwaggerUi.js index 0f46efa2..93ac6d38 100644 --- a/src/main/javascript/SwaggerUi.js +++ b/src/main/javascript/SwaggerUi.js @@ -13,7 +13,12 @@ window.SwaggerUi = Backbone.Router.extend({ // SwaggerUi accepts all the same options as SwaggerApi initialize: function(options) { options = options || {}; - if(!options.highlightSizeThreshold) { + + if (options.defaultModelRendering !== 'model') { + options.defaultModelRendering = 'schema'; + } + + if (!options.highlightSizeThreshold) { options.highlightSizeThreshold = 100000; } diff --git a/src/main/javascript/view/OperationView.js b/src/main/javascript/view/OperationView.js index 206118e2..85b8a82f 100644 --- a/src/main/javascript/view/OperationView.js +++ b/src/main/javascript/view/OperationView.js @@ -19,6 +19,14 @@ SwaggerUi.Views.OperationView = Backbone.View.extend({ this.parentId = this.model.parentId; this.nickname = this.model.nickname; this.model.encodedParentId = encodeURIComponent(this.parentId); + + if (opts.swaggerOptions) { + this.model.defaultRendering = opts.swaggerOptions.defaultModelRendering; + + if (opts.swaggerOptions.showRequestHeaders) { + this.model.showRequestHeaders = true; + } + } return this; }, @@ -174,12 +182,9 @@ SwaggerUi.Views.OperationView = Backbone.View.extend({ signature: this.model.responseClassSignature }; } - var opts = this.options.swaggerOptions; - if (opts.showRequestHeaders) { - this.model.showRequestHeaders = true; - } $(this.el).html(Handlebars.templates.operation(this.model)); if (signatureModel) { + signatureModel.defaultRendering = this.model.defaultRendering; responseSignatureView = new SwaggerUi.Views.SignatureView({ model: signatureModel, router: this.router, @@ -238,6 +243,7 @@ SwaggerUi.Views.OperationView = Backbone.View.extend({ addParameter: function(param, consumes) { // Render a parameter param.consumes = consumes; + param.defaultRendering = this.model.defaultRendering; var paramView = new SwaggerUi.Views.ParameterView({ model: param, tagName: 'tr', @@ -248,6 +254,7 @@ SwaggerUi.Views.OperationView = Backbone.View.extend({ addStatusCode: function(statusCode) { // Render status codes + statusCode.defaultRendering = this.model.defaultRendering; var statusCodeView = new SwaggerUi.Views.StatusCodeView({ model: statusCode, tagName: 'tr', diff --git a/src/main/javascript/view/ParameterView.js b/src/main/javascript/view/ParameterView.js index ff8a296a..bd1bd6ef 100644 --- a/src/main/javascript/view/ParameterView.js +++ b/src/main/javascript/view/ParameterView.js @@ -49,7 +49,8 @@ SwaggerUi.Views.ParameterView = Backbone.View.extend({ var signatureModel = { sampleJSON: this.model.sampleJSON, isParam: true, - signature: this.model.signature + signature: this.model.signature, + defaultRendering: this.model.defaultRendering }; if (this.model.sampleJSON) { diff --git a/src/main/javascript/view/SignatureView.js b/src/main/javascript/view/SignatureView.js index c0f8bd40..37d56d7d 100644 --- a/src/main/javascript/view/SignatureView.js +++ b/src/main/javascript/view/SignatureView.js @@ -15,8 +15,12 @@ SwaggerUi.Views.SignatureView = Backbone.View.extend({ $(this.el).html(Handlebars.templates.signature(this.model)); - this.switchToSnippet(); - + if (this.model.defaultRendering === 'model') { + this.switchToDescription(); + } else { + this.switchToSnippet(); + } + this.isParam = this.model.isParam; if (this.isParam) { diff --git a/src/main/javascript/view/StatusCodeView.js b/src/main/javascript/view/StatusCodeView.js index 163d32b3..32b6c7d5 100644 --- a/src/main/javascript/view/StatusCodeView.js +++ b/src/main/javascript/view/StatusCodeView.js @@ -14,6 +14,7 @@ SwaggerUi.Views.StatusCodeView = Backbone.View.extend({ sampleJSON: JSON.stringify(this.router.api.models[this.model.responseModel].createJSONSample(), null, 2), isParam: false, signature: this.router.api.models[this.model.responseModel].getMockSignature(), + defaultRendering: this.model.defaultRendering }; var responseModelView = new SwaggerUi.Views.SignatureView({model: responseModel, tagName: 'div'});