Render response examples as highlighted text, if it is not an Object. (…

…#82) Closes #81 Closes #77 - Examples may be provided as string and need not be a JSON object see https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v2.0/yaml/api-with-examples.yaml - in such a case, we don't want to JSON.stringify() the example but display it as is.
bootprint · Dec 17, 2016 · fa9f407 · fa9f407
1 parent aa87b43
commit fa9f407
Show file tree

Hide file tree

Showing 5 changed files with 222 additions and 1 deletion.
diff --git a/handlebars/helpers.js b/handlebars/helpers.js
@@ -1,3 +1,10 @@
+var _ = require('lodash')
+var highlight = require('highlight.js')
+
+highlight.configure({
+  'useBR': true
+})
+
 module.exports = {
   'swagger--collection-format': function (value, paramName) {
     return {
@@ -71,5 +78,35 @@ module.exports = {
       '510': 'Not Extended', // rfc2774, 7
       '511': 'Network Authentication Required' // rfc6585, 6
     }[code]
+  },
+
+  /**
+   * Render the value of an [Example object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#exampleObject)
+   *
+   * * If the mime-type is `application/json`, and the example is an object,
+   *   it will be stringified
+   *
+   * * If the mime-type is `application/xml`, and the example is an object,
+   *   the json should be converted to XML (which is not the case at the moment
+   *   TODO, help wanted)
+   *
+   * @param {any} example the value of an [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#exampleObject)
+   * @param {string} mimeType the mime-type of this example
+   */
+  'swagger--example': function (example, mimeType, options, customize) {
+    if (_.isObject(example)) {
+      switch (mimeType) {
+        case 'application/json':
+          example = require('json-stable-stringify')(example, {space: 4})
+          break
+        case 'application/xml':
+          // TODO: This should actually convert the example to XML but I don't know how yet. "help wanted"
+          example = require('json-stable-stringify')(example, {space: 4})
+          break
+      }
+    }
+    var highlighted = highlight.highlightAuto(String(example)).value
+    var fixMarkup = highlight.fixMarkup(highlighted)
+    return new customize.engine.SafeString('<pre>' + fixMarkup + '</pre>')
   }
 }
diff --git a/handlebars/partials/swagger/response.hbs b/handlebars/partials/swagger/response.hbs
@@ -12,7 +12,7 @@
     {{#each response.examples}}
         <div class="col-md-6 sw-response-examples">
             <div class="label label-default">Example for {{@key}}</div>
-            {{json .}}
+            {{swagger--example . @key}}
         </div>
     {{/each}}
 

diff --git a/package.json b/package.json
@@ -19,6 +19,8 @@
   },
   "dependencies": {
     "bootprint-json-schema": "<1.0.0",
+    "highlight.js": "^8.9.1",
+    "json-stable-stringify": "^1.0.1",
     "lodash": "^3.9.3"
   },
   "repository": {

diff --git a/test/response-string-example/response-string-example-spec.js b/test/response-string-example/response-string-example-spec.js
@@ -0,0 +1,24 @@
+/*!
+ * bootprint-swagger <https://github.com/nknapp/bootprint-swagger>
+ *
+ * Copyright (c) 2015 Nils Knappmeier.
+ * Released under the MIT license.
+ */
+
+/* global describe */
+/* global it */
+/* global before */
+var expect = require('chai').expect
+var core = require('../core')
+
+describe('The response string-examples fixture', function () {
+  this.timeout(10000)
+  var context = {}
+  before(function () {
+    return core.run(require.resolve('./swagger.yaml'), __dirname, context)
+  })
+  it('should render the response examples', function () {
+    expect(context.$('dd.sw-response-200 .sw-response-examples').text(),
+    'Examples consisting of only a string should not be JSON.stringified').not.to.match(/\\n/)
+  })
+})
diff --git a/test/response-string-example/swagger.yaml b/test/response-string-example/swagger.yaml
@@ -0,0 +1,158 @@
+# From: https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v2.0/yaml/api-with-examples.yaml
+swagger: "2.0"
+info:
+  title: Simple API overview
+  version: v2
+paths:
+  /:
+    get:
+      operationId: listVersionsv2
+      summary: List API versions
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: |-
+            200 300 response
+          examples:
+            application/json: |-
+              {
+                  "versions": [
+                      {
+                          "status": "CURRENT",
+                          "updated": "2011-01-21T11:33:21Z",
+                          "id": "v2.0",
+                          "links": [
+                              {
+                                  "href": "http://127.0.0.1:8774/v2/",
+                                  "rel": "self"
+                              }
+                          ]
+                      }
+                  ]
+              }
+            application/xml: |-
+              <xml>
+                <some random="element">with contents</some>
+              </xml>
+        "300":
+          description: |-
+            200 300 response
+          examples:
+            application/json: |-
+              {
+                  "versions": [
+                      {
+                          "status": "CURRENT",
+                          "updated": "2011-01-21T11:33:21Z",
+                          "id": "v2.0",
+                          "links": [
+                              {
+                                  "href": "http://127.0.0.1:8774/v2/",
+                                  "rel": "self"
+                              }
+                          ]
+                      },
+                      {
+                          "status": "EXPERIMENTAL",
+                          "updated": "2013-07-23T11:33:21Z",
+                          "id": "v3.0",
+                          "links": [
+                              {
+                                  "href": "http://127.0.0.1:8774/v3/",
+                                  "rel": "self"
+                              }
+                          ]
+                      }
+                  ]
+              }
+  /v2:
+    get:
+      operationId: getVersionDetailsv2
+      summary: Show API version details
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: |-
+            200 203 response
+          examples:
+            application/json: |-
+              {
+                  "version": {
+                      "status": "CURRENT",
+                      "updated": "2011-01-21T11:33:21Z",
+                      "media-types": [
+                          {
+                              "base": "application/xml",
+                              "type": "application/vnd.openstack.compute+xml;version=2"
+                          },
+                          {
+                              "base": "application/json",
+                              "type": "application/vnd.openstack.compute+json;version=2"
+                          }
+                      ],
+                      "id": "v2.0",
+                      "links": [
+                          {
+                              "href": "http://127.0.0.1:8774/v2/",
+                              "rel": "self"
+                          },
+                          {
+                              "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf",
+                              "type": "application/pdf",
+                              "rel": "describedby"
+                          },
+                          {
+                              "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl",
+                              "type": "application/vnd.sun.wadl+xml",
+                              "rel": "describedby"
+                          },
+                          {
+                            "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl",
+                            "type": "application/vnd.sun.wadl+xml",
+                            "rel": "describedby"
+                          }
+                      ]
+                  }
+              }
+        "203":
+          description: |-
+            200 203 response
+          examples:
+            application/json: |-
+              {
+                  "version": {
+                      "status": "CURRENT",
+                      "updated": "2011-01-21T11:33:21Z",
+                      "media-types": [
+                          {
+                              "base": "application/xml",
+                              "type": "application/vnd.openstack.compute+xml;version=2"
+                          },
+                          {
+                              "base": "application/json",
+                              "type": "application/vnd.openstack.compute+json;version=2"
+                          }
+                      ],
+                      "id": "v2.0",
+                      "links": [
+                          {
+                              "href": "http://23.253.228.211:8774/v2/",
+                              "rel": "self"
+                          },
+                          {
+                              "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf",
+                              "type": "application/pdf",
+                              "rel": "describedby"
+                          },
+                          {
+                              "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl",
+                              "type": "application/vnd.sun.wadl+xml",
+                              "rel": "describedby"
+                          }
+                      ]
+                  }
+              }
+consumes:
+- application/json