Skip to content

Latest commit

 

History

History
383 lines (335 loc) · 18.1 KB

configuration.md

File metadata and controls

383 lines (335 loc) · 18.1 KB
Raw

Configuration

How to configure

Swagger UI accepts configuration parameters in three locations.

From lowest to highest precedence:

  • configuration object passed as an argument to Swagger UI (SwaggerUI({ ... }))
  • configuration document fetched from a specified configUrl
  • configuration items passed as key/value pairs in the URL query string

Parameters

Parameters with dots in their names are single strings used to organize subordinate parameters, and are not indicative of a nested structure.

For readability, parameters are grouped by category and sorted alphabetically.

Type notations are formatted like so:

  • String="" means a String type with a default value of "".
  • String=["a"*, "b", "c", "d"] means a String type that can be a, b, c, or d, with the * indicating that a is the default value.
Core
Parameter name Docker variable Description
configUrl CONFIG_URL String. URL to fetch external configuration document from.
dom_id DOM_ID String, REQUIRED if domNode is not provided. The ID of a DOM element inside which SwaggerUI will put its user interface.
domNode Unavailable Element, REQUIRED if dom_id is not provided. The HTML DOM element inside which SwaggerUI will put its user interface. Overrides dom_id.
spec SPEC Object={}. A JavaScript object describing the OpenAPI definition. When used, the url parameter will not be parsed. This is useful for testing manually-generated definitions without hosting them.
url URL String. The URL pointing to API definition (normally swagger.json or swagger.yaml). Will be ignored if urls or spec is used.
urls URLS Array. An array of API definition objects ([{url: "<url1>", name: "<name1>"},{url: "<url2>", name: "<name2>"}]) used by Topbar plugin. When used and Topbar plugin is enabled, the url parameter will not be parsed. Names and URLs must be unique among all items in this array, since they're used as identifiers.
urls.primaryName URLS_PRIMARY_NAME String. When using urls, you can use this subparameter. If the value matches the name of a spec provided in urls, that spec will be displayed when Swagger UI loads, instead of defaulting to the first spec in urls.
queryConfigEnabled QUERY_CONFIG_ENABLED Boolean=false. Enables overriding configuration parameters via URL search params.
Plugin system

Read more about the plugin system in the Customization documentation.

Parameter name Docker variable Description
layout Unavailable String="BaseLayout". The name of a component available via the plugin system to use as the top-level layout for Swagger UI.
plugins Unavailable Array=[]. An array of plugin functions to use in Swagger UI.
presets Unavailable Array=[SwaggerUI.presets.ApisPreset]. An array of presets to use in Swagger UI. Usually, you'll want to include ApisPreset if you use this option.
Display
Parameter name Docker variable Description
deepLinking DEEP_LINKING Boolean=false. If set to true, enables deep linking for tags and operations. See the Deep Linking documentation for more information.
displayOperationId DISPLAY_OPERATION_ID Boolean=false. Controls the display of operationId in operations list. The default is false.
defaultModelsExpandDepth DEFAULT_MODELS_EXPAND_DEPTH Number=1. The default expansion depth for models (set to -1 completely hide the models).
defaultModelExpandDepth DEFAULT_MODEL_EXPAND_DEPTH Number=1. The default expansion depth for the model on the model-example section.
defaultModelRendering DEFAULT_MODEL_RENDERING String=["example"*, "model"]. Controls how the model is 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.)
displayRequestDuration DISPLAY_REQUEST_DURATION Boolean=false. Controls the display of the request duration (in milliseconds) for "Try it out" requests.
docExpansion DOC_EXPANSION String=["list"*, "full", "none"]. Controls the default expansion setting for the operations and tags. It can be 'list' (expands only the tags), 'full' (expands the tags and operations) or 'none' (expands nothing).
filter FILTER Boolean=false OR String. 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 Boolean to enable or disable, or a 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.
maxDisplayedTags MAX_DISPLAYED_TAGS Number. If set, limits the number of tagged operations displayed to at most this many. The default is to show all operations.
operationsSorter Unavailable Function=(a => a). 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.
showExtensions SHOW_EXTENSIONS Boolean=false. Controls the display of vendor extension (x-) fields and values for Operations, Parameters, Responses, and Schema.
showCommonExtensions SHOW_COMMON_EXTENSIONS Boolean=false. Controls the display of extensions (pattern, maxLength, minLength, maximum, minimum) fields and values for Parameters.
tagsSorter Unavailable Function=(a => a). 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() 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.
useUnsafeMarkdown USE_UNSAFE_MARKDOWN Boolean=false. When enabled, sanitizer will leave style, class and data-* attributes untouched on all HTML Elements declared inside markdown strings. This parameter is Deprecated and will be removed in 4.0.0.
onComplete Unavailable Function=NOOP. Provides a mechanism to be notified when Swagger UI has finished rendering a newly provided definition.
syntaxHighlight Unavailable Set to false to deactivate syntax highlighting of payloads and cURL command, can be otherwise an object with the activated and theme properties.
syntaxHighlight.activated Unavailable Boolean=true. Whether syntax highlighting should be activated or not.
syntaxHighlight.theme Unavailable String=["agate"*, "arta", "monokai", "nord", "obsidian", "tomorrow-night", "idea"]. Highlight.js syntax coloring theme to use. (Only these 7 styles are available.)
tryItOutEnabled TRY_IT_OUT_ENABLED Boolean=false. Controls whether the "Try it out" section should be enabled by default.
requestSnippetsEnabled Unavailable Boolean=false. Enables the request snippet section. When disabled, the legacy curl snippet will be used.
requestSnippets Unavailable 
Object={
  generators: {
    curl_bash: {
      title: "cURL (bash)",
      syntax: "bash"
    },
    curl_powershell: {
      title: "cURL (PowerShell)",
      syntax: "powershell"
    },
    curl_cmd: {
      title: "cURL (CMD)",
      syntax: "bash"
    },
  },
  defaultExpanded: true,
  languages: null, 
  // e.g. only show curl bash = ["curl_bash"]
}
This is the default configuration section for the requestSnippets plugin.
Network
Parameter name Docker variable Description
oauth2RedirectUrl OAUTH2_REDIRECT_URL String. OAuth redirect URL.
requestInterceptor Unavailable Function=(a => a). MUST be a function. Function to intercept remote definition, "Try it out", and OAuth 2.0 requests. Accepts one argument requestInterceptor(request) and must return the modified request, or a Promise that resolves to the modified request.
request.curlOptions Unavailable Array. If set, MUST be an array of command line options available to the curl command. This can be set on the mutated request in the requestInterceptor function. For example request.curlOptions = ["-g", "--limit-rate 20k"]
responseInterceptor Unavailable Function=(a => a). MUST be a function. Function to intercept remote definition, "Try it out", and OAuth 2.0 responses. Accepts one argument responseInterceptor(response) and must return the modified response, or a Promise that resolves to the modified response.
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.
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.
validatorUrl VALIDATOR_URL String="https://validator.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). Setting it to either none, 127.0.0.1 or localhost will disable validation.
withCredentials WITH_CREDENTIALS Boolean=false If set to true, enables passing credentials, as defined in the Fetch standard, in CORS requests that are sent by the browser. Note that Swagger UI cannot currently set cookies cross-domain (see swagger-js#1163) - as a result, you will have to rely on browser-supplied cookies (which this setting enables sending) that Swagger UI cannot control.
Macros
Parameter name Docker variable Description
modelPropertyMacro Unavailable Function. Function to set default values to each property in model. Accepts one argument modelPropertyMacro(property), property is immutable
parameterMacro Unavailable 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
Authorization
Parameter name Docker variable Description
persistAuthorization PERSIST_AUTHORIZATION Boolean=false. If set to true, it persists authorization data and it would not be lost on browser close/refresh

Instance methods

💡 Take note! These are methods, not parameters.

Method name Docker variable Description
initOAuth See oauth2.md (configObj) => void. Provide Swagger UI with information about your OAuth server - see the OAuth 2.0 documentation for more information.
preauthorizeBasic Unavailable (authDefinitionKey, username, password) => action. Programmatically set values for a Basic authorization scheme.
preauthorizeApiKey Unavailable (authDefinitionKey, apiKeyValue) => action. Programmatically set values for an API key or Bearer authorization scheme. In case of OpenAPI 3.0 Bearer scheme, apiKeyValue must contain just the token itself without the Bearer prefix.

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.

Below are the general guidelines for using the environment variable interface.

String variables

Set the value to whatever string you'd like, taking care to escape characters where necessary

Example:

FILTER="myFilterValue"
LAYOUT="BaseLayout"
Boolean variables

Set the value to true or false.

Example:

DISPLAY_OPERATION_ID="true"
DEEP_LINKING="false"
Number variables

Set the value to n, where n is the number you'd like to provide.

Example:

DEFAULT_MODELS_EXPAND_DEPTH="5"
DEFAULT_MODEL_EXPAND_DEPTH="7"
Array variables

Set the value to the literal array value you'd like, taking care to escape characters where necessary.

Example:

SUPPORTED_SUBMIT_METHODS="[\"get\", \"post\"]"
URLS="[ { url: \"https://petstore.swagger.io/v2/swagger.json\", name: \"Petstore\" } ]"
Object variables

Set the value to the literal object value you'd like, taking care to escape characters where necessary.

Example:

SPEC="{ \"openapi\": \"3.0.0\" }"

Docker-Compose

.env file example encoding

SUPPORTED_SUBMIT_METHODS=['get', 'post']
URLS=[ { url: 'https://petstore.swagger.io/v2/swagger.json', name: 'Petstore' } ]