From c7b215b6bb56c8097f02f518265cbdd3f04acdb0 Mon Sep 17 00:00:00 2001 From: Vladimir Gorej Date: Mon, 8 Nov 2021 11:32:07 +0100 Subject: [PATCH] docs(configuration): document requestSnippetsEnabled config option Along with that fix formatting of request snippet value. --- docs/usage/configuration.md | 256 ++++++++++++++++++++++++++++++++---- 1 file changed, 233 insertions(+), 23 deletions(-) diff --git a/docs/usage/configuration.md b/docs/usage/configuration.md index 38c54f02..9105ce2b 100644 --- a/docs/usage/configuration.md +++ b/docs/usage/configuration.md @@ -51,29 +51,239 @@ Parameter name | Docker variable | Description ##### 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](/docs/usage/deep-linking.md) 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()](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. -`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 `activate` and `theme` properties. -`syntaxHighlight.activate` | _Unavailable_ | `Boolean=true`. Whether syntax highlighting should be activated or not. -`syntaxHighlight.theme` | _Unavailable_ | `String=["agate"*, "arta", "monokai", "nord", "obsidian", "tomorrow-night"]`. [Highlight.js](https://highlightjs.org/static/demo/) syntax coloring theme to use. (Only these 6 styles are available.) -`tryItOutEnabled` | `TRY_IT_OUT_ENABLED` | `Boolean=false`. Controls whether the "Try it out" section should be enabled by default. -`requestSnippets` | _Unavailable_ | `Object`. This is the default configuration section for the the requestSnippets plugin.
requestSnippets: {
  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"\]
}, - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter nameDocker variableDescription
deepLinkingDEEP_LINKINGBoolean=false. If set to true, enables + deep linking for tags and operations. See the Deep Linking + documentation for more information. +
displayOperationId + DISPLAY_OPERATION_IDBoolean=false. Controls the display of operationId in + operations list. The default is false. +
defaultModelsExpandDepth + DEFAULT_MODELS_EXPAND_DEPTHNumber=1. The default expansion depth for models (set + to -1 completely hide the models). +
defaultModelExpandDepth + DEFAULT_MODEL_EXPAND_DEPTHNumber=1. The default expansion depth for the model on + the model-example section. +
defaultModelRendering + DEFAULT_MODEL_RENDERINGString=["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_DURATIONBoolean=false. Controls the display of the request + duration (in milliseconds) for "Try it out" requests. +
docExpansion + DOC_EXPANSIONString=["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). +
filterFILTERBoolean=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_TAGSNumber. If set, limits the number of tagged operations + displayed to at most this many. The default is to show all + operations. +
+ operationsSorter + UnavailableFunction=(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_EXTENSIONSBoolean=false. Controls the display of vendor extension + (x-) fields and values for Operations, Parameters, + Responses, and Schema. +
showCommonExtensions + SHOW_COMMON_EXTENSIONSBoolean=false. Controls the display of extensions + (pattern, maxLength, + minLength, maximum, minimum) + fields and values for Parameters. +
tagsSorterUnavailableFunction=(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_MARKDOWNBoolean=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. +
onCompleteUnavailableFunction=NOOP. Provides a mechanism to be notified when + Swagger UI has finished rendering a newly provided definition. +
+ syntaxHighlight + UnavailableSet to false to deactivate syntax highlighting of + payloads and cURL command, can be otherwise an object with the + activate and theme properties. +
syntaxHighlight.activate + UnavailableBoolean=true. Whether syntax highlighting should be + activated or not. +
syntaxHighlight.theme + UnavailableString=["agate"*, "arta", "monokai", "nord", "obsidian", + "tomorrow-night"]. Highlight.js + syntax coloring theme to use. (Only these 6 styles are available.) +
+ tryItOutEnabled + TRY_IT_OUT_ENABLEDBoolean=false. Controls whether the "Try it out" + section should be enabled by default. +
requestSnippetsEnabled + UnavailableBoolean=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 the + requestSnippets plugin. +
##### Network