redo of PR #88, #89, #90

This new section displays how a complex datatype should look like providing some sample code for the developer using Swagger.

Cakefile

@@ -10,6 +10,7 @@ sourceFiles  = [
   'view/OperationView'
   'view/StatusCodeView'
   'view/ParameterView'
+  'view/SignatureView'
 ]
 
 

lib/swagger.js

@@ -53,6 +53,9 @@
       this.progress('fetching resource list: ' + this.discoveryUrl);
       return jQuery.getJSON(this.discoveryUrl, function(response) {
         var res, resource, _i, _j, _len, _len1, _ref, _ref1;
+        if (response.apiVersion != null) {
+          _this.apiVersion = response.apiVersion;
+        }
         if ((response.basePath != null) && jQuery.trim(response.basePath).length > 0) {
           _this.basePath = response.basePath;
           if (_this.basePath.match(/^HTTP/i) == null) {
@@ -334,6 +337,17 @@
       return returnVal;
     };
 
+    SwaggerModel.prototype.createJSONSample = function(modelToIgnore) {
+      var prop, result, _i, _len, _ref;
+      result = {};
+      _ref = this.properties;
+      for (_i = 0, _len = _ref.length; _i < _len; _i++) {
+        prop = _ref[_i];
+        result[prop.name] = prop.getSampleValue(modelToIgnore);
+      }
+      return result;
+    };
+
     return SwaggerModel;
 
   })();
@@ -363,6 +377,24 @@
       }
     }
 
+    SwaggerModelProperty.prototype.getSampleValue = function(modelToIgnore) {
+      var result;
+      if ((this.refModel != null) && (!(this.refModel === modelToIgnore))) {
+        result = this.refModel.createJSONSample(this.refModel);
+      } else {
+        if (this.isArray) {
+          result = this.refDataType;
+        } else {
+          result = this.dataType;
+        }
+      }
+      if (this.isArray) {
+        return [result];
+      } else {
+        return result;
+      }
+    };
+
     SwaggerModelProperty.prototype.toString = function() {
       var str;
       str = this.name + ': ' + this.dataTypeWithRef;
@@ -424,6 +456,7 @@
           parameter.allowableValues.values = this.resource.api.booleanValues;
         }
         parameter.signature = this.getSignature(parameter.dataType, this.resource.models);
+        parameter.sampleJSON = this.getSampleJSON(parameter.dataType, this.resource.models);
         if (parameter.allowableValues != null) {
           if (parameter.allowableValues.valueType === "RANGE") {
             parameter.isRange = true;
@@ -478,6 +511,17 @@
       }
     };
 
+    SwaggerOperation.prototype.getSampleJSON = function(dataType, models) {
+      var isPrimitive, listType, val;
+      listType = this.isListType(dataType);
+      isPrimitive = ((listType != null) && models[listType]) || (models[dataType] != null) ? false : true;
+      val = isPrimitive ? void 0 : (listType != null ? models[listType].createJSONSample() : models[dataType].createJSONSample());
+      if (val) {
+        val = listType ? [val] : val;
+        return JSON.stringify(val, null, 2);
+      }
+    };
+
     SwaggerOperation.prototype["do"] = function(args, callback, error) {
       var body, headers;
       if (args == null) {

src/main/coffeescript/view/HeaderView.coffee

@@ -13,7 +13,7 @@ class HeaderView extends Backbone.View
   showPetStore: (e) ->
     @trigger(
       'update-swagger-ui'
-      {discoveryUrl:"http://petstore.swagger.wordnik.com/api/resources.json", apiKey:"special-key"}
+      {discoveryUrl:"http://petstore.swagger.wordnik.com/api/api-docs.json", apiKey:"special-key"}
     )
 
   showWordnikDev: (e) ->

src/main/coffeescript/view/OperationView.coffee

@@ -104,7 +104,7 @@ class OperationView extends Backbone.View
         complete: (data) =>
           @showCompleteStatus(data)
 
-      obj.contentType = "application/json" if (obj.type.toLowerCase() == "put" or obj.type.toLowerCase() == "patch")
+      obj.contentType = "application/json" if (obj.type.toLowerCase() == "post" or obj.type.toLowerCase() == "put" or obj.type.toLowerCase() == "patch")
       obj.contentType = false if isFileUpload
       jQuery.ajax(obj)
       false
@@ -134,7 +134,7 @@ class OperationView extends Backbone.View
   # puts the response data in UI
   showStatus: (data) ->
     try
-      response_body = "<pre>" + JSON.stringify(JSON.parse(data.responseText), null, 2).replace(/\n/g, "<br>") + "</pre>"
+      response_body = '<pre class="json"><code>' + JSON.stringify(JSON.parse(data.responseText), null, 2) + "</code></pre>"
     catch error
       response_body = "<span style='color:red'>&nbsp;&nbsp;&nbsp;[unable to parse as json; raw response below]</span><br><pre>" + data.responseText + "</pre>"
     $(".response_code", $(@el)).html "<pre>" + data.status + "</pre>"
@@ -143,6 +143,7 @@ class OperationView extends Backbone.View
     $(".response", $(@el)).slideDown()
     $(".response_hider", $(@el)).show()
     $(".response_throbber", $(@el)).hide()
+    hljs.highlightBlock($('.response_body', $(@el))[0])
 
   toggleOperationContent: ->
     elem = $('#' + @model.resourceName + "_" + @model.nickname + "_" + @model.httpMethod + "_content");

src/main/coffeescript/view/ParameterView.coffee

@@ -8,6 +8,12 @@ class ParameterView extends Backbone.View
     template = @template()
     $(@el).html(template(@model))
 
+    if @model.sampleJSON
+        signatureView = new SignatureView({model: @model, tagName: 'div'})
+        $('.model-signature', $(@el)).append signatureView.render().el
+    else
+        $('.model-signature', $(@el)).html(@model.signature)
+
     @
 
   # Return an appropriate template based on if the parameter is a list, readonly, required

src/main/coffeescript/view/SignatureView.coffee

@@ -0,0 +1,43 @@
+class SignatureView extends Backbone.View
+  events: {
+  'click a.description-link'       : 'switchToDescription'
+  'click a.snippet-link'           : 'switchToSnippet'
+  'mousedown .snippet'          : 'snippetToTextArea'
+  }
+
+  initialize: ->
+
+  render: ->
+    template = @template()
+    $(@el).html(template(@model))
+
+    @switchToDescription()
+
+    @
+
+  template: ->
+      Handlebars.templates.signature
+
+  # handler for show signature
+  switchToDescription: (e) ->
+    e?.preventDefault()
+    $(".snippet", $(@el)).hide()
+    $(".description", $(@el)).show()
+    $('.description-link', $(@el)).addClass('selected')
+    $('.snippet-link', $(@el)).removeClass('selected')
+    
+  # handler for show sample
+  switchToSnippet: (e) ->
+    e?.preventDefault()
+    $(".description", $(@el)).hide()
+    $(".snippet", $(@el)).show()
+    $('.snippet-link', $(@el)).addClass('selected')
+    $('.description-link', $(@el)).removeClass('selected')
+
+  # handler for snippet to text area
+  snippetToTextArea: (e) ->
+    e?.preventDefault()
+    textArea = $('textarea', $(@el.parentNode.parentNode.parentNode))
+    if $.trim(textArea.val()) == ''
+        textArea.val(@model.sampleJSON)
+    

src/main/html/css/hightlight.default.css

@@ -0,0 +1,135 @@
+/*
+
+Original style from softwaremaniacs.org (c) Ivan Sagalaev <Maniac@SoftwareManiacs.Org>
+
+*/
+
+pre code {
+  display: block; padding: 0.5em;
+  background: #F0F0F0;
+}
+
+pre code,
+pre .subst,
+pre .tag .title,
+pre .lisp .title,
+pre .clojure .built_in,
+pre .nginx .title {
+  color: black;
+}
+
+pre .string,
+pre .title,
+pre .constant,
+pre .parent,
+pre .tag .value,
+pre .rules .value,
+pre .rules .value .number,
+pre .preprocessor,
+pre .ruby .symbol,
+pre .ruby .symbol .string,
+pre .aggregate,
+pre .template_tag,
+pre .django .variable,
+pre .smalltalk .class,
+pre .addition,
+pre .flow,
+pre .stream,
+pre .bash .variable,
+pre .apache .tag,
+pre .apache .cbracket,
+pre .tex .command,
+pre .tex .special,
+pre .erlang_repl .function_or_atom,
+pre .markdown .header {
+  color: #800;
+}
+
+pre .comment,
+pre .annotation,
+pre .template_comment,
+pre .diff .header,
+pre .chunk,
+pre .markdown .blockquote {
+  color: #888;
+}
+
+pre .number,
+pre .date,
+pre .regexp,
+pre .literal,
+pre .smalltalk .symbol,
+pre .smalltalk .char,
+pre .go .constant,
+pre .change,
+pre .markdown .bullet,
+pre .markdown .link_url {
+  color: #080;
+}
+
+pre .label,
+pre .javadoc,
+pre .ruby .string,
+pre .decorator,
+pre .filter .argument,
+pre .localvars,
+pre .array,
+pre .attr_selector,
+pre .important,
+pre .pseudo,
+pre .pi,
+pre .doctype,
+pre .deletion,
+pre .envvar,
+pre .shebang,
+pre .apache .sqbracket,
+pre .nginx .built_in,
+pre .tex .formula,
+pre .erlang_repl .reserved,
+pre .prompt,
+pre .markdown .link_label,
+pre .vhdl .attribute,
+pre .clojure .attribute,
+pre .coffeescript .property {
+  color: #88F
+}
+
+pre .keyword,
+pre .id,
+pre .phpdoc,
+pre .title,
+pre .built_in,
+pre .aggregate,
+pre .css .tag,
+pre .javadoctag,
+pre .phpdoc,
+pre .yardoctag,
+pre .smalltalk .class,
+pre .winutils,
+pre .bash .variable,
+pre .apache .tag,
+pre .go .typename,
+pre .tex .command,
+pre .markdown .strong,
+pre .request,
+pre .status {
+  font-weight: bold;
+}
+
+pre .markdown .emphasis {
+  font-style: italic;
+}
+
+pre .nginx .built_in {
+  font-weight: normal;
+}
+
+pre .coffeescript .javascript,
+pre .javascript .xml,
+pre .tex .formula,
+pre .xml .javascript,
+pre .xml .vbscript,
+pre .xml .css,
+pre .xml .cdata {
+  opacity: 0.5;
+}

src/main/html/css/screen.css

@@ -1145,9 +1145,9 @@ body ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operatio
     display: block;
     margin: 0 0 0 0;
     padding: 0;
-    background-color: #faebf2;
+    background-color: #FCE9E3;
     border: 1px solid black;
-    border-color: #f0cecb;
+    border-color: #F5D5C3;
 }
 
 body ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.patch div.heading h3 {
@@ -1168,7 +1168,7 @@ body ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operatio
 
 body ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.patch div.heading h3 span.http_method a {
     text-transform: uppercase;
-    background-color: #993300;
+    background-color: #D38042;
     text-decoration: none;
     color: white;
     display: inline-block;
@@ -1228,12 +1228,12 @@ body ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operatio
 
 body ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.patch div.heading ul.options li {
     border-right-color: #f0cecb;
-    color: #993300;
+    color: #D38042;
     font-size: 0.9em;
 }
 
 body ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.patch div.heading ul.options li a {
-    color: #993300;
+    color: #D38042;
     text-decoration: none;
 }
 
@@ -1263,7 +1263,7 @@ body ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operatio
 }
 
 body ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.patch div.content h4 {
-    color: #993300;
+    color: #D38042;
     font-size: 1.1em;
     margin: 0;
     padding: 15px 0 5px 0px;
@@ -1271,7 +1271,7 @@ body ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operatio
 
 body ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.patch div.content form input[type='text'].error {
     outline: 2px solid black;
-    outline-color: #cc0000;
+    outline-color: #F5D5C3;
 }
 
 body ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operation.patch div.content div.sandbox_header {
@@ -1509,9 +1509,73 @@ body ul#resources li.resource ul.endpoints li.endpoint ul.operations li.operatio
     font-size: 1em;
     line-height: 1.5em;
 }
-.model-signature span {
+.model-signature .description span {
     font-size: 0.9em;
     line-height: 1.5em;
 }
-.model-signature span:nth-child(odd)    { color:#333; }
-.model-signature span:nth-child(even)    { color:#C5862B; }
+.model-signature .description span:nth-child(odd)    { color:#333; }
+.model-signature .description span:nth-child(even)    { color:#C5862B; }
+.model-signature .signature-nav a {
+    text-decoration: none;
+    color: #AAA;
+}
+
+.model-signature pre {
+    font-size: .85em;
+    line-height: 1.2em;
+    overflow: auto;
+    max-height: 200px;
+    cursor: pointer;
+}
+
+.model-signature pre:hover {
+    background-color: #ffffdd;
+}
+
+.model-signature .snippet small {
+    font-size: 0.75em;
+}
+
+.model-signature .signature-container {
+    clear: both;
+}
+
+.model-signature .signature-nav a:hover {
+    text-decoration: underline;
+    color: black;
+}
+
+.model-signature .signature-nav .selected {
+    color: black;
+    text-decoration: none;
+}
+
+.model-signature ul.signature-nav {
+    float: none;
+    clear: both;
+    overflow: hidden;
+    margin: 0;
+    padding: 0;
+    display: block;
+    clear: none;
+    float: right;
+    margin-right: 5px;
+    margin-bottom: 5px;
+}
+
+.model-signature ul.signature-nav li {
+    float: left;
+    clear: none;
+    margin: 0;
+    padding: 2px 10px;
+    border-right: 1px solid #dddddd;
+}
+
+.model-signature ul.signature-nav li:last-child {
+    padding-right: 0;
+    border-right: none;
+}
+
+pre code {
+  background: none;
+}

src/main/html/index.html

@@ -3,6 +3,7 @@
 <head>
     <title>Swagger UI</title>
     <link href='http://fonts.googleapis.com/css?family=Droid+Sans:400,700' rel='stylesheet' type='text/css'/>
+    <link href='css/hightlight.default.css' media='screen' rel='stylesheet' type='text/css'/>
     <link href='css/screen.css' media='screen' rel='stylesheet' type='text/css'/>
     <script src='lib/jquery-1.8.0.min.js' type='text/javascript'></script>
     <script src='lib/jquery.slideto.min.js' type='text/javascript'></script>
@@ -13,6 +14,7 @@
     <script src='lib/backbone-min.js' type='text/javascript'></script>
     <script src='lib/swagger.js' type='text/javascript'></script>
     <script src='swagger-ui.js' type='text/javascript'></script>
+    <script src='lib/highlight.7.3.pack.js' type='text/javascript'></script>
 
     <style type="text/css">
         .swagger-ui-wrap {
@@ -43,7 +45,7 @@
     <script type="text/javascript">
         $(function () {
             window.swaggerUi = new SwaggerUi({
-                discoveryUrl:"http://petstore.swagger.wordnik.com/api/resources.json",
+                discoveryUrl:"http://petstore.swagger.wordnik.com/api/api-docs.json",
                 apiKey:"special-key",
                 dom_id:"swagger-ui-container",
                 supportHeaderParams: false,
@@ -54,6 +56,7 @@
                         console.log(swaggerApi);
                         console.log(swaggerUi);
                     }
+                  $('pre code').each(function(i, e) {hljs.highlightBlock(e)});
                 },
                 onFailure: function(data) {
                 	if(console) {

src/main/javascript/doc.js

@@ -115,7 +115,7 @@ var Docs = {
 	},
 
 	toggleEndpointListForResource: function(resource) {
-		var elem = $('li[id^=resource_' + Docs.escapeResourceName(resource) + '] ul.endpoints');
+		var elem = $('li#resource_' + Docs.escapeResourceName(resource) + ' ul.endpoints');
 		if (elem.is(':visible')) {
 			Docs.collapseEndpointListForResource(resource);
 		} else {
@@ -125,24 +125,27 @@ var Docs = {
 
 	// Expand resource
 	expandEndpointListForResource: function(resource) {
-		$('[id^=resource_' + resource + ']').addClass('active');
+		var resource = Docs.escapeResourceName(resource);
+		$('li#resource_' + resource).addClass('active');
 
-		var elem = $('li[id^=resource_' + Docs.escapeResourceName(resource) + '] ul.endpoints');
+		var elem = $('li#resource_' + resource + ' ul.endpoints');
 		elem.slideDown();
 	},
 
 	// Collapse resource and mark as explicitly closed
 	collapseEndpointListForResource: function(resource) {
-		$('[id^=resource_' + resource + ']').removeClass('active');
+		var resource = Docs.escapeResourceName(resource);
+		$('li#resource_' + resource).removeClass('active');
 
-		var elem = $('li[id^=resource_' + Docs.escapeResourceName(resource) + '] ul.endpoints');
+		var elem = $('li#resource_' + resource + ' ul.endpoints');
 		elem.slideUp();
 	},
 
 	expandOperationsForResource: function(resource) {
 		// Make sure the resource container is open..
 		Docs.expandEndpointListForResource(resource);
-		$('li[id^=resource_' + Docs.escapeResourceName(resource) + '] li.operation div.content').each(function() {
+
+		$('li#resource_' + Docs.escapeResourceName(resource) + ' li.operation div.content').each(function() {
 			Docs.expandOperation($(this));
 		});
 	},
@@ -150,13 +153,14 @@ var Docs = {
 	collapseOperationsForResource: function(resource) {
 		// Make sure the resource container is open..
 		Docs.expandEndpointListForResource(resource);
-		$('li[id^=resource_' + Docs.escapeResourceName(resource) + '] li.operation div.content').each(function() {
+
+		$('li#resource_' + Docs.escapeResourceName(resource) + ' li.operation div.content').each(function() {
 			Docs.collapseOperation($(this));
 		});
 	},
 
 	escapeResourceName: function(resource) {
-		 return resource.replace(/[!"#$%&'()*+,.\/:;<=>?@\[\\\]\^`{|}~]/g, "\\$&")
+		return resource.replace(/[!"#$%&'()*+,.\/:;<=>?@\[\\\]\^`{|}~]/g, "\\$&");
 	},
 
 	expandOperation: function(elem) {
@@ -167,4 +171,4 @@ var Docs = {
 		elem.slideUp();
 	}
 
-};
+};

src/main/template/main.handlebars

@@ -6,6 +6,9 @@
     <div class="footer">
         <br>
         <br>
-        <h4 style="color: #999">[<span style="font-variant: small-caps">base url</span>: {{basePath}}]</h4>
+        <h4 style="color: #999">[ <span style="font-variant: small-caps">base url</span>: {{basePath}}
+        {{#if apiVersion}}
+        , <span style="font-variant: small-caps">api version</span>: {{apiVersion}}
+        {{/if}}]</h4>
     </div>
-</div>
+</div>

src/main/template/param.handlebars

@@ -22,6 +22,6 @@
 </td>
 <td>{{{description}}}</td>
 <td>
-    <span class="model-signature">{{{signature}}}</span>
+    <span class="model-signature"></span>
 </td>
 

src/main/template/param_list.handlebars

@@ -18,4 +18,4 @@
     </select>
 </td>
 <td>{{{description}}}</td>
-<td><span class="model-signature">{{{signature}}}</span></td>
+<td><span class="model-signature"></span></td>

src/main/template/param_readonly.handlebars

@@ -7,4 +7,4 @@
     {{/if}}
 </td>
 <td>{{{description}}}</td>
-<td><span class="model-signature">{{{signature}}}</span></td>
+<td><span class="model-signature"></span></td>

src/main/template/param_readonly_required.handlebars

@@ -7,4 +7,4 @@
     {{/if}}
 </td>
 <td>{{{description}}}</td>
-<td><span class="model-signature">{{{signature}}}</span></td>
+<td><span class="model-signature"></span></td>

src/main/template/param_required.handlebars

@@ -25,4 +25,4 @@
 <td>
     <strong>{{{description}}}</strong>
 </td>
-<td><span class="model-signature">{{{signature}}}</span></td>
+<td><span class="model-signature"></span></td>

src/main/template/signature.handlebars

@@ -0,0 +1,18 @@
+<div>
+<ul class="signature-nav">
+    <li><a class="description-link" href="#">Description</a></li>
+    <li><a class="snippet-link" href="#">Snippet</a></li>
+</ul>
+<div>
+
+<div class="signature-container">
+    <div class="description">
+        {{{signature}}}
+    </div>
+
+    <div class="snippet">
+        <pre><code>{{sampleJSON}}</code></pre>
+        <small>Click to set as parameter value</small>
+    </div>
+</div>
+