feature: add `withCredentials` configuration key (via #5149)

* Add the withCredentials configuration key

It enables passing credentials in CORS requests. e.g. Cookies and
Authorization headers.

* Improve withCredentials documentation

* Add unit tests for the withCredentials config

* Update configuration.md

* Update configuration.md

* only set `withCredentials` Fetch flag if the config value is truthy

there are some workarounds in the wild today that involve setting `withCredentials` on `system.fn.fetch` directly. 

this approach avoids mangling those existing workarounds!

* add more test cases

* Update configs-wrap-actions.js

* Update index.js

docker/configurator/variables.js

@@ -86,6 +86,10 @@ const standardVariables = {
   VALIDATOR_URL: {
     type: "string",
     name: "validatorUrl"
+  },
+  WITH_CREDENTIALS: {
+    type: "boolean",
+    name: "withCredentials",
   }
 }
 
@@ -102,4 +106,4 @@ const legacyVariables = {
   }
 }
 
-module.exports = Object.assign({}, standardVariables, legacyVariables)
\ No newline at end of file
+module.exports = Object.assign({}, standardVariables, legacyVariables)

docs/usage/configuration.md

@@ -71,6 +71,7 @@ Parameter name | Docker variable | Description
 <a name="showMutatedRequest"></a>`showMutatedRequest` | `SHOW_MUTATED_REQUEST` | `Boolean=true`. If set to `true`, uses the mutated request returned from a requestInterceptor to produce the curl command in the UI, otherwise the request before the requestInterceptor was applied is used.
 <a name="supportedSubmitMethods"></a>`supportedSubmitMethods` | `SUPPORTED_SUBMIT_METHODS` | `Array=["get", "put", "post", "delete", "options", "head", "patch", "trace"]`. List of HTTP methods that have the Try it out feature enabled. An empty array disables Try it out for all operations. This does not filter the operations from the display.
 <a name="validatorUrl"></a>`validatorUrl` | `VALIDATOR_URL` | `String="https://online.swagger.io/validator" OR null`. By default, Swagger-UI attempts to validate specs against swagger.io's online validator. You can use this parameter to set a different validator URL, for example for locally deployed validators ([Validator Badge](https://github.com/swagger-api/validator-badge)). Setting it to `null` will disable validation.
+<a name="withCredentials"></a>`withCredentials` | `WITH_CREDENTIALS` | `Boolean=false` If set to `true`, enables passing credentials, [as defined in the Fetch standard](https://fetch.spec.whatwg.org/#credentials), in CORS requests that are sent by the browser. Note that Swagger UI cannot currently set cookies cross-domain (see [swagger-js#1163](https://github.com/swagger-api/swagger-js/issues/1163)) - as a result, you will have to rely on browser-supplied cookies (which this setting enables sending) that Swagger UI cannot control.
 
 ##### Macros
 
@@ -81,7 +82,7 @@ Parameter name | Docker variable | Description
 
 ### Instance methods
 
-**💡 Take note! These are methods, not parameters**. 
+**💡 Take note! These are methods, not parameters**.
 
 Method name | Docker variable | Description
 --- | --- | -----
@@ -91,7 +92,7 @@ Method name | Docker variable | Description
 
 ### Docker
 
-If you're using the Docker image, you can also control most of these options with environment variables. Each parameter has its environment variable name noted, if available. 
+If you're using the Docker image, you can also control most of these options with environment variables. Each parameter has its environment variable name noted, if available.
 
 Below are the general guidelines for using the environment variable interface.
 

src/core/index.js

@@ -51,6 +51,7 @@ module.exports = function SwaggerUI(opts) {
     defaultModelsExpandDepth: 1,
     showExtensions: false,
     showCommonExtensions: false,
+    withCredentials: undefined,
     supportedSubmitMethods: [
       "get",
       "put",

src/core/plugins/swagger-js/configs-wrap-actions.js

+export const loaded = (ori, system) => (...args) => {
+  ori(...args)
+  const value = system.getConfigs().withCredentials
+  
+  if(value !== undefined) {
+    system.fn.fetch.withCredentials = typeof value === "string" ? (value === "true") : !!value
+  }
+}

src/core/plugins/swagger-js/index.js

 import Swagger from "swagger-client"
+import * as configsWrapActions from "./configs-wrap-actions"
 
 module.exports = function({ configs, getConfigs }) {
   return {
@@ -22,6 +23,11 @@ module.exports = function({ configs, getConfigs }) {
       },
       serializeRes: Swagger.serializeRes,
       opId: Swagger.helpers.opId
-    }
+    },
+    statePlugins: {
+      configs: {
+        wrapActions: configsWrapActions
+      }
+    },
   }
 }

test/core/plugins/swagger-js/withCredentials.js

+import expect, { createSpy } from "expect"
+import { loaded } from "corePlugins/swagger-js/configs-wrap-actions"
+
+describe("swagger-js plugin - withCredentials", () => {
+  it("should have no effect by default", () => {
+    const system = {
+      fn: {
+        fetch: createSpy().andReturn(Promise.resolve())
+      },
+      getConfigs: () => ({})
+    }
+    const oriExecute = createSpy()
+
+    const loadedFn = loaded(oriExecute, system)
+    loadedFn()
+
+    expect(oriExecute.calls.length).toBe(1)
+    expect(system.fn.fetch.withCredentials).toBe(undefined)
+  })
+
+  it("should allow setting flag to true via config", () => {
+    const system = {
+      fn: {
+        fetch: createSpy().andReturn(Promise.resolve())
+      },
+      getConfigs: () => ({
+        withCredentials: true
+      })
+    }
+    const oriExecute = createSpy()
+
+    const loadedFn = loaded(oriExecute, system)
+    loadedFn()
+
+    expect(oriExecute.calls.length).toBe(1)
+    expect(system.fn.fetch.withCredentials).toBe(true)
+  })
+  
+  it("should allow setting flag to false via config", () => {
+    const system = {
+      fn: {
+        fetch: createSpy().andReturn(Promise.resolve())
+      },
+      getConfigs: () => ({
+        withCredentials: false
+      })
+    }
+    const oriExecute = createSpy()
+
+    const loadedFn = loaded(oriExecute, system)
+    loadedFn()
+
+    expect(oriExecute.calls.length).toBe(1)
+    expect(system.fn.fetch.withCredentials).toBe(false)
+  })
+  
+   it("should allow setting flag to true via config as string", () => {
+    // for query string config
+    const system = {
+      fn: {
+        fetch: createSpy().andReturn(Promise.resolve())
+      },
+      getConfigs: () => ({
+        withCredentials: "true"
+      })
+    }
+    const oriExecute = createSpy()
+
+    const loadedFn = loaded(oriExecute, system)
+    loadedFn()
+
+    expect(oriExecute.calls.length).toBe(1)
+    expect(system.fn.fetch.withCredentials).toBe(true)
+  })
+  
+  it("should allow setting flag to false via config as string", () => {
+    // for query string config
+    const system = {
+      fn: {
+        fetch: createSpy().andReturn(Promise.resolve())
+      },
+      getConfigs: () => ({
+        withCredentials: "false"
+      })
+    }
+    const oriExecute = createSpy()
+
+    const loadedFn = loaded(oriExecute, system)
+    loadedFn()
+
+    expect(oriExecute.calls.length).toBe(1)
+    expect(system.fn.fetch.withCredentials).toBe(false)
+  })
+})