Merge branch 'master' into array-model-markdown-description

.github/issue_template.md

@@ -14,14 +14,18 @@ or anything that violates the specifications.
 
 <!--- Provide a general summary of the issue in the title above -->
 
+<!--- 
+  If you aren't sure what Swagger-UI version, see this guide: https://github.com/swagger-api/swagger-ui/blob/master/docs/version-detection.md
+--->
+
 
 | Q                               | A
 | ------------------------------- | -------
 | Bug or feature request?         |  
 | Which Swagger/OpenAPI version?  |
 | Which Swagger-UI version?       |
 | How did you install Swagger-UI? | 
-| Which broswer & version?        |
+| Which browser & version?        |
 | Which operating system?         | 
 
 

README.md

@@ -10,10 +10,10 @@
 
 As a brand new version, written from the ground up, there are some known issues and unimplemented features. Check out the [Known Issues](#known-issues) section for more details.
 
-This repo publishes to two different NPM packages:
+This repository publishes to two different NPM modules:
 
-* [swagger-ui](https://www.npmjs.com/package/swagger-ui) is intended for use as a node module.
-* [swagger-ui-dist](https://www.npmjs.com/package/swagger-ui-dist) comes pre-bundled with all dependencies and can be incorporated directly in a webapp.
+* [swagger-ui](https://www.npmjs.com/package/swagger-ui) is a traditional npm module intended for use in JavaScript web application projects that are capable of resolving dependencies (via Webpack, Browserify, etc).
+* [swagger-ui-dist](https://www.npmjs.com/package/swagger-ui-dist) is a dependency-free module that includes everything you need to serve Swagger-UI in a server-side project, or a web project that can't resolve npm module dependencies.
 
 For the older version of swagger-ui, refer to the [*2.x branch*](https://github.com/swagger-api/swagger-ui/tree/2.x).
 
@@ -22,7 +22,7 @@ The OpenAPI Specification has undergone 5 revisions since initial creation in 20
 
 Swagger UI Version | Release Date | OpenAPI Spec compatibility | Notes
 ------------------ | ------------ | -------------------------- | -----
-3.1.4 | 2017-08-05 | 2.0, 3.0 | [tag v3.1.4](https://github.com/swagger-api/swagger-ui/tree/v3.1.4)
+3.2.2 | 2017-09-22 | 2.0, 3.0 | [tag v3.2.2](https://github.com/swagger-api/swagger-ui/tree/v3.2.2)
 3.0.21 | 2017-07-26 | 2.0 | [tag v3.0.21](https://github.com/swagger-api/swagger-ui/tree/v3.0.21)
 2.2.10 | 2017-01-04 | 1.1, 1.2, 2.0 | [tag v2.2.10](https://github.com/swagger-api/swagger-ui/tree/v2.2.10)
 2.1.5 | 2016-07-20 | 1.1, 1.2, 2.0 | [tag v2.1.5](https://github.com/swagger-api/swagger-ui/tree/v2.1.5)
@@ -46,7 +46,7 @@ Will start nginx with swagger-ui on port 80.
 Or you can provide your own swagger.json on your host
 
 ```
-docker run -p 80:8080 -e "SWAGGER_JSON=/foo/swagger.json" -v /bar:/foo swaggerapi/swagger-ui
+docker run -p 80:8080 -e SWAGGER_JSON=/foo/swagger.json -v /bar:/foo swaggerapi/swagger-ui
 ```
 
 ##### Prerequisites
@@ -151,6 +151,8 @@ domNode | The HTML DOM element inside which SwaggerUi will put the user interfac
 oauth2RedirectUrl | OAuth redirect URL
 tagsSorter | Apply a sort to the tag list of each API. It can be 'alpha' (sort by paths alphanumerically) or a function (see [Array.prototype.sort()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) to learn how to write a sort function). Two tag name strings are passed to the sorter for each pass. Default is the order determined by Swagger-UI.
 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 'Example Value' links.) It can be set to 'model' or 'example', and the default is 'example'.
+defaultModelExpandDepth | The default expansion depth for models.  The default value is 1.
 configUrl | Configs URL
 parameterMacro | MUST be a function. Function to set default value to parameters. Accepts two arguments parameterMacro(operation, parameter). Operation and parameter are objects passed for context, both remain immutable
 modelPropertyMacro | MUST be a function. Function to set default values to each property in model. Accepts one argument modelPropertyMacro(property), property is immutable
@@ -160,6 +162,9 @@ displayRequestDuration | Controls the display of the request duration (in millis
 maxDisplayedTags | If set, limits the number of tagged operations displayed to at most this many. The default is to show all operations.
 filter | If set, enables filtering. The top bar will show an edit box that you can use to filter the tagged operations that are shown. Can be true/false to enable or disable, or an explicit filter string in which case filtering will be enabled using that string as the filter expression. Filtering is case sensitive matching the filter expression anywhere inside the tag.
 deepLinking | If set to `true`, enables dynamic deep linking for tags and operations. [Docs](https://github.com/swagger-api/swagger-ui/blob/master/docs/deep-linking.md)
+requestInterceptor | MUST be a function.  Function to intercept try-it-out requests.  Accepts one argument requestInterceptor(request) and must return the potentially modified request.
+responseInterceptor | MUST be a function.  Function to intercept try-it-out responses.  Accepts one argument responseInterceptor(response) and must return the potentially modified response.
+showMutatedRequest | If set to `true` (the default), uses the mutated request returned from a rquestInterceptor to produce the curl command in the UI, otherwise the request before the requestInterceptor was applied is used.
 
 ### Plugins
 

dev-helpers/oauth2-redirect.html

@@ -11,7 +11,11 @@
         var redirectUrl = oauth2.redirectUrl;
         var isValid, qp, arr;
 
-        qp = (window.location.hash || location.search).substring(1);
+        if (/code|token|error/.test(window.location.hash)) {
+            qp = window.location.hash.substring(1);
+        } else {
+            qp = location.search.substring(1);
+        }
 
         arr = qp.split("&")
         arr.forEach(function (v,i,_arr) { _arr[i] = '"' + v.replace('=', '":"') + '"';})

dist/oauth2-redirect.html

@@ -11,7 +11,11 @@
         var redirectUrl = oauth2.redirectUrl;
         var isValid, qp, arr;
 
-        qp = (window.location.hash || location.search).substring(1);
+        if (/code|token|error/.test(window.location.hash)) {
+            qp = window.location.hash.substring(1);
+        } else {
+            qp = location.search.substring(1);
+        }
 
         arr = qp.split("&")
         arr.forEach(function (v,i,_arr) { _arr[i] = '"' + v.replace('=', '":"') + '"';})

docs/version-detection.md

@@ -0,0 +1,54 @@
+# Detecting your Swagger-UI version
+
+At times, you're going to need to know which version of Swagger-UI you use. 
+
+The first step would be to detect which major version you currently use, as the method of detecting the version has changed. If your Swagger-UI has been heavily modified and you cannot detect from the look and feel which major version you use, you'd have to try both methods to get the exact version.
+
+To help you visually detect which version you're using, we've included supporting images.
+
+
+# Swagger-UI 3.X
+
+![Swagger-UI 3](images/swagger-ui3.png)
+
+Some distinct identifiers to Swagger-UI 3.X:
+- The API version appears as a badge next to its title.
+- If there are schemes or authorizations, they'd appear in a bar above the operations.
+- Try it out functionality is not enabled by default.
+- All the response codes in the operations appear at after the parameters.
+- There's a models section after the operations.
+
+If you've determined this is the version you have, to find the exact version:
+- Open your browser's web console (changes between browsers)
+- Type `versions` in the console and execute the call.
+- You might need to expand the result, until you get a string similar to `swaggerUi : Object { version: "3.1.6", gitRevision: "g786cd47", gitDirty: true, … }`.
+- The version taken from that example would be `3.1.6`.
+
+Note: This functionality was added in 3.0.8. If you're unable to execute it, you're likely to use an older version, and in that case the first step would be to upgrade.
+
+
+# Swagger-UI 2.X and under
+
+![Swagger-UI 2](images/swagger-ui2.png)
+
+Some distinct identifiers to Swagger-UI 3.X:
+- The API version appears at the bottom of the page.
+- Schemes are not rendered.
+- Authorization, if rendered, will appear next to the navigation bar.
+- Try it out functionality is enabled by default.
+- The successful response code would appear above the parameters, the rest below them.
+- There's no models section after the operations.
+
+If you've determined this is the version you have, to find the exact version:
+- Navigate to the sources of the UI. Either on your disk or via the view page source functionality in your browser.
+- Find an open the `swagger-ui.js`
+- At the top of the page, there would be a comment containing the exact version of swagger-ui. This example shows version `2.2.9`:
+
+```
+/**
+ * swagger-ui - Swagger UI is a dependency-free collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API
+ * @version v2.2.9
+ * @link http://swagger.io
+ * @license Apache-2.0
+ */
+ ```

package.json

@@ -1,6 +1,6 @@
 {
   "name": "swagger-ui",
-  "version": "3.1.4",
+  "version": "3.2.2",
   "main": "dist/swagger-ui.js",
   "repository": "[email protected]:swagger-api/swagger-ui.git",
   "contributors": [
@@ -41,6 +41,9 @@
   "dependencies": {
     "base64-js": "^1.2.0",
     "brace": "0.7.0",
+    "classnames": "^2.2.5",
+    "commonmark": "^0.28.1",
+    "css.escape": "1.5.1",
     "deep-extend": "0.4.1",
     "expect": "1.20.2",
     "getbase": "^2.8.2",
@@ -65,17 +68,17 @@
     "react-motion": "0.4.4",
     "react-object-inspector": "0.2.1",
     "react-redux": "^4.x.x",
-    "react-remarkable": "1.1.1",
     "react-split-pane": "0.1.57",
     "redux": "^3.x.x",
     "redux-immutable": "3.0.8",
     "redux-logger": "*",
+    "remarkable": "^1.7.1",
     "reselect": "2.5.3",
     "sanitize-html": "^1.14.1",
     "scroll-to-element": "^2.0.0",
     "serialize-error": "2.0.0",
     "shallowequal": "0.2.2",
-    "swagger-client": "3.0.19",
+    "swagger-client": "^3.1.2",
     "url-parse": "^1.1.8",
     "whatwg-fetch": "0.11.1",
     "worker-loader": "^0.7.1",

src/core/components/array-model.jsx

@@ -30,6 +30,11 @@ export default class ArrayModel extends Component {
         <span className="model-title__text">{ title }</span>
       </span>
 
+    /* 
+    Note: we set `name={null}` in <Model> below because we don't want
+    the name of the current Model passed (and displayed) as the name of the array element Model
+    */ 
+
     return <span className="model">
       <ModelCollapse title={titleEl} collapsed={ depth > expandDepth } collapsedContent="[...]">
         [
@@ -42,7 +47,7 @@ export default class ArrayModel extends Component {
             !description ? null :
               <Markdown source={ description } />
           }
-          <span><Model { ...this.props } schema={ items } required={ false } depth={ depth + 1 } /></span>
+          <span><Model { ...this.props } name={null} schema={ items } required={ false } depth={ depth + 1 } /></span>
         ]
       </ModelCollapse>
     </span>

src/core/components/layouts/base.jsx

@@ -8,6 +8,8 @@ export default class BaseLayout extends React.Component {
     errActions: PropTypes.object.isRequired,
     specActions: PropTypes.object.isRequired,
     specSelectors: PropTypes.object.isRequired,
+    oas3Selectors: PropTypes.object.isRequired,
+    oas3Actions: PropTypes.object.isRequired,
     layoutSelectors: PropTypes.object.isRequired,
     layoutActions: PropTypes.object.isRequired,
     getComponent: PropTypes.func.isRequired
@@ -19,7 +21,14 @@ export default class BaseLayout extends React.Component {
   }
 
   render() {
-    let { specSelectors, specActions, getComponent, layoutSelectors } = this.props
+    let {
+      specSelectors,
+      specActions,
+      getComponent,
+      layoutSelectors,
+      oas3Selectors,
+      oas3Actions
+    } = this.props
 
     let info = specSelectors.info()
     let url = specSelectors.url()
@@ -28,13 +37,15 @@ export default class BaseLayout extends React.Component {
     let securityDefinitions = specSelectors.securityDefinitions()
     let externalDocs = specSelectors.externalDocs()
     let schemes = specSelectors.schemes()
+    let servers = specSelectors.servers()
 
     let Info = getComponent("info")
     let Operations = getComponent("operations", true)
     let Models = getComponent("Models", true)
     let AuthorizeBtn = getComponent("authorizeBtn", true)
     let Row = getComponent("Row")
     let Col = getComponent("Col")
+    let Servers = getComponent("Servers")
     let Errors = getComponent("errors", true)
 
     let isLoading = specSelectors.loadingStatus() === "loading"
@@ -82,6 +93,22 @@ export default class BaseLayout extends React.Component {
               </div>
             ) : null }
 
+            { servers && servers.size ? (
+              <div className="server-container">
+                <Col className="servers wrapper" mobile={12}>
+                  <Servers
+                    servers={servers}
+                    currentServer={oas3Selectors.selectedServer()}
+                    setSelectedServer={oas3Actions.setSelectedServer}
+                    setServerVariableValue={oas3Actions.setServerVariableValue}
+                    getServerVariable={oas3Selectors.serverVariableValue}
+                    getEffectiveServerValue={oas3Selectors.serverEffectiveValue}
+                    />
+                </Col>
+              </div>
+
+            ) : null}
+
             {
               filter === null || filter === false ? null :
                 <div className="filter-container">

src/core/components/live-response.jsx

@@ -29,13 +29,18 @@ Duration.propTypes = {
 export default class LiveResponse extends React.Component {
   static propTypes = {
     response: PropTypes.object.isRequired,
+    specSelectors: PropTypes.object.isRequired,
+    pathMethod: PropTypes.object.isRequired,
     getComponent: PropTypes.func.isRequired,
-    displayRequestDuration: PropTypes.bool.isRequired
+    displayRequestDuration: PropTypes.bool.isRequired,
+    getConfigs: PropTypes.func.isRequired
   }
 
   render() {
-    const { request, response, getComponent, displayRequestDuration } = this.props
+    const { response, getComponent, getConfigs, displayRequestDuration, specSelectors, pathMethod } = this.props
+    const { showMutatedRequest } = getConfigs()
 
+    const curlRequest = showMutatedRequest ? specSelectors.mutatedRequestFor(pathMethod[0], pathMethod[1]) : specSelectors.requestFor(pathMethod[0], pathMethod[1])
     const status = response.get("status")
     const url = response.get("url")
     const headers = response.get("headers").toJS()
@@ -55,7 +60,7 @@ export default class LiveResponse extends React.Component {
 
     return (
       <div>
-        { request && <Curl request={ request }/> }
+        { curlRequest && <Curl request={ curlRequest }/> }
         <h4>Server response</h4>
         <table className="responses-table">
           <thead>

src/core/components/model-example.jsx

@@ -7,14 +7,19 @@ export default class ModelExample extends React.Component {
     specSelectors: PropTypes.object.isRequired,
     schema: PropTypes.object.isRequired,
     example: PropTypes.any.isRequired,
-    isExecute: PropTypes.bool
+    isExecute: PropTypes.bool,
+    getConfigs: PropTypes.func.isRequired
   }
 
   constructor(props, context) {
     super(props, context)
-
+    let { getConfigs } = this.props
+    let { defaultModelRendering } = getConfigs()
+    if (defaultModelRendering !== "example" && defaultModelRendering !== "model") {
+      defaultModelRendering = "example"
+    }
     this.state = {
-      activeTab: "example"
+      activeTab: defaultModelRendering
     }
   }
 
@@ -27,7 +32,8 @@ export default class ModelExample extends React.Component {
   }
 
   render() {
-    let { getComponent, specSelectors, schema, example, isExecute } = this.props
+    let { getComponent, specSelectors, schema, example, isExecute, getConfigs } = this.props
+    let { defaultModelExpandDepth } = getConfigs()
     const ModelWrapper = getComponent("ModelWrapper")
 
     return <div>
@@ -47,7 +53,7 @@ export default class ModelExample extends React.Component {
           !isExecute && this.state.activeTab === "model" && <ModelWrapper schema={ schema }
                                                      getComponent={ getComponent }
                                                      specSelectors={ specSelectors }
-                                                     expandDepth={ 1 } />
+                                                     expandDepth={ defaultModelExpandDepth } />
 
 
         }