checks/personal_area_php
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

api

Browse Source
This commit is contained in:
Kavalar
2024-05-24 15:27:07 +03:00
parent 17df2ce6a9
commit fc1da2c238
643 changed files with 110185 additions and 231 deletions
Download Patch File Download Diff File Expand all files Collapse all files

391
frontend/web/api-doc/docs/usage/configuration.md Normal file
View File

@ -0,0 +1,391 @@
# Configuration
### How to configure
Swagger UI accepts configuration parameters in four locations.
From lowest to highest precedence:
- The `swagger-config.yaml` in the project root directory, if it exists, is baked into the application
- 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
--- | --- | -----
<a name="configUrl"></a>`configUrl` | `CONFIG_URL` | `String`. URL to fetch external configuration document from.
<a name="dom_id"></a>`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.
<a name="domNode"></a>`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`.
<a name="spec"></a>`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.
<a name="url"></a>`url` | `URL` | `String`. The URL pointing to API definition (normally `swagger.json` or `swagger.yaml`). Will be ignored if `urls` or `spec` is used.
<a name="urls"></a>`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.
<a name="urls.primaryName"></a>`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`.
<a name="queryConfigEnabled"></a>`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](/docs/customization/overview.md).
Parameter name | Docker variable | Description
--- | --- | -----
<a name="layout"></a>`layout` | _Unavailable_ | `String="BaseLayout"`. The name of a component available via the plugin system to use as the top-level layout for Swagger UI.
<a name="pluginsOptions"></a>`pluginsOptions` | _Unavailable_ | `Object`. A Javascript object to configure plugin integration and behaviors (see below).
<a name="plugins"></a>`plugins` | _Unavailable_ | `Array=[]`. An array of plugin functions to use in Swagger UI.
<a name="presets"></a>`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.
##### Plugins options
Parameter name | Docker variable | Description
--- | --- | -----
<a name="pluginLoadType"></a>`pluginLoadType` | _Unavailable_ | `String=["legacy", "chain"]`. Control behavior of plugins when targeting the same component with wrapComponent.<br/>- `legacy` (default) : last plugin takes precedence over the others<br/>- `chain` : chain wrapComponents when targeting the same core component, allowing multiple plugins to wrap the same component
##### Display
<table role="table">
<thead>
<tr>
<th>Parameter name</th>
<th>Docker variable</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><a name="user-content-deeplinking"></a><code>deepLinking</code></td>
<td><code>DEEP_LINKING</code></td>
<td><code>Boolean=false</code>. If set to <code>true</code>, enables
deep linking for tags and operations. See the <a
href="/docs/usage/deep-linking.md">Deep Linking
documentation</a> for more information.
</td>
</tr>
<tr>
<td><a name="user-content-displayoperationid"></a><code>displayOperationId</code>
</td>
<td><code>DISPLAY_OPERATION_ID</code></td>
<td><code>Boolean=false</code>. Controls the display of operationId in
operations list. The default is <code>false</code>.
</td>
</tr>
<tr>
<td><a name="user-content-defaultmodelsexpanddepth"></a><code>defaultModelsExpandDepth</code>
</td>
<td><code>DEFAULT_MODELS_EXPAND_DEPTH</code></td>
<td><code>Number=1</code>. The default expansion depth for models (set
to -1 completely hide the models).
</td>
</tr>
<tr>
<td><a name="user-content-defaultmodelexpanddepth"></a><code>defaultModelExpandDepth</code>
</td>
<td><code>DEFAULT_MODEL_EXPAND_DEPTH</code></td>
<td><code>Number=1</code>. The default expansion depth for the model on
the model-example section.
</td>
</tr>
<tr>
<td><a name="user-content-defaultmodelrendering"></a><code>defaultModelRendering</code>
</td>
<td><code>DEFAULT_MODEL_RENDERING</code></td>
<td><code>String=["example"*, "model"]</code>. 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.)
</td>
</tr>
<tr>
<td><a name="user-content-displayrequestduration"></a><code>displayRequestDuration</code>
</td>
<td><code>DISPLAY_REQUEST_DURATION</code></td>
<td><code>Boolean=false</code>. Controls the display of the request
duration (in milliseconds) for "Try it out" requests.
</td>
</tr>
<tr>
<td><a name="user-content-docexpansion"></a><code>docExpansion</code>
</td>
<td><code>DOC_EXPANSION</code></td>
<td><code>String=["list"*, "full", "none"]</code>. 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).
</td>
</tr>
<tr>
<td><a name="user-content-filter"></a><code>filter</code></td>
<td><code>FILTER</code></td>
<td><code>Boolean=false OR String</code>. 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.
</td>
</tr>
<tr>
<td>
<a name="user-content-maxdisplayedtags"></a><code>maxDisplayedTags</code>
</td>
<td><code>MAX_DISPLAYED_TAGS</code></td>
<td><code>Number</code>. If set, limits the number of tagged operations
displayed to at most this many. The default is to show all
operations.
</td>
</tr>
<tr>
<td>
<a name="user-content-operationssorter"></a><code>operationsSorter</code>
</td>
<td><em>Unavailable</em></td>
<td><code>Function=(a =&gt; a)</code>. 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.
</td>
</tr>
<tr>
<td>
<a name="user-content-showextensions"></a><code>showExtensions</code>
</td>
<td><code>SHOW_EXTENSIONS</code></td>
<td><code>Boolean=false</code>. Controls the display of vendor extension
(<code>x-</code>) fields and values for Operations, Parameters,
Responses, and Schema.
</td>
</tr>
<tr>
<td><a name="user-content-showcommonextensions"></a><code>showCommonExtensions</code>
</td>
<td><code>SHOW_COMMON_EXTENSIONS</code></td>
<td><code>Boolean=false</code>. Controls the display of extensions
(<code>pattern</code>, <code>maxLength</code>,
<code>minLength</code>, <code>maximum</code>, <code>minimum</code>)
fields and values for Parameters.
</td>
</tr>
<tr>
<td><a name="user-content-tagsorter"></a><code>tagsSorter</code></td>
<td><em>Unavailable</em></td>
<td><code>Function=(a =&gt; a)</code>. Apply a sort to the tag list of
each API. It can be 'alpha' (sort by paths alphanumerically) or a
function (see <a
href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort"
rel="nofollow">Array.prototype.sort()</a> 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.
</td>
</tr>
<tr>
<td>
<a name="user-content-useunsafemarkdown"></a><code>useUnsafeMarkdown</code>
</td>
<td><code>USE_UNSAFE_MARKDOWN</code></td>
<td><code>Boolean=false</code>. When enabled, sanitizer will leave
<code>style</code>, <code>class</code> and <code>data-*</code>
attributes untouched on all HTML Elements declared inside markdown
strings. This parameter is <strong>Deprecated</strong> and will be
removed in <code>4.0.0</code>.
</td>
</tr>
<tr>
<td><a name="user-content-oncomplete"></a><code>onComplete</code></td>
<td><em>Unavailable</em></td>
<td><code>Function=NOOP</code>. Provides a mechanism to be notified when
Swagger UI has finished rendering a newly provided definition.
</td>
</tr>
<tr>
<td>
<a name="user-content-syntaxhighlight"></a><code>syntaxHighlight</code>
</td>
<td><em>Unavailable</em></td>
<td>Set to <code>false</code> to deactivate syntax highlighting of
payloads and cURL command, can be otherwise an object with the
<code>activate</code> and <code>theme</code> properties.
</td>
</tr>
<tr>
<td><a name="user-content-syntaxhighlight.activate"></a><code>syntaxHighlight.activate</code>
</td>
<td><em>Unavailable</em></td>
<td><code>Boolean=true</code>. Whether syntax highlighting should be
activated or not.
</td>
</tr>
<tr>
<td><a name="user-content-syntaxhighlight.theme"></a><code>syntaxHighlight.theme</code>
</td>
<td><em>Unavailable</em></td>
<td><code>String=["agate"*, "arta", "monokai", "nord", "obsidian",
"tomorrow-night"]</code>. <a
href="https://highlightjs.org/static/demo/" rel="nofollow">Highlight.js</a>
syntax coloring theme to use. (Only these 6 styles are available.)
</td>
</tr>
<tr>
<td>
<a name="user-content-tryitoutenabled"></a><code>tryItOutEnabled</code>
</td>
<td><code>TRY_IT_OUT_ENABLED</code></td>
<td><code>Boolean=false</code>. Controls whether the "Try it out"
section should be enabled by default.
</td>
</tr>
<tr>
<td><a name="user-content-requestsnippetsenabled"></a><code>requestSnippetsEnabled</code>
</td>
<td><em>Unavailable</em></td>
<td><code>Boolean=false</code>. Enables the request snippet section.
When disabled, the legacy curl snippet will be used.
</td>
</tr>
<tr>
<td>
<a name="user-content-requestsnippets"></a><code>requestSnippets</code>
</td>
<td><em>Unavailable</em></td>
<td>
<pre lang="javascript">
<code>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"]
}
</code>
</pre>
This is the default configuration section for the the
requestSnippets plugin.
</td>
</tr>
</tbody>
</table>
##### Network
Parameter name | Docker variable | Description
--- | --- | -----
<a name="oauth2RedirectUrl"></a>`oauth2RedirectUrl` | `OAUTH2_REDIRECT_URL` | `String`. OAuth redirect URL.
<a name="requestInterceptor"></a>`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.
<a name="request.curlOptions"></a>`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"]`
<a name="responseInterceptor"></a>`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.
<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://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](https://github.com/swagger-api/validator-badge)). Setting it to either `none`, `127.0.0.1` or `localhost` 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
Parameter name | Docker variable | Description
--- | --- | -----
<a name="modelPropertyMacro"></a>`modelPropertyMacro` | _Unavailable_ | `Function`. Function to set default values to each property in model. Accepts one argument modelPropertyMacro(property), property is immutable
<a name="parameterMacro"></a>`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
--- | --- | -----
<a name="persistAuthorization"></a>`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
--- | --- | -----
<a name="initOAuth"></a>`initOAuth` | [_See `oauth2.md`_](./oauth2.md) | `(configObj) => void`. Provide Swagger UI with information about your OAuth server - see the [OAuth 2.0 documentation](./oauth2.md) for more information.
<a name="preauthorizeBasic"></a>`preauthorizeBasic` | _Unavailable_ | `(authDefinitionKey, username, password) => action`. Programmatically set values for a Basic authorization scheme.
<a name="preauthorizeApiKey"></a>`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:
```sh
FILTER="myFilterValue"
LAYOUT="BaseLayout"
```
##### Boolean variables
Set the value to `true` or `false`.
Example:
```sh
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:
```sh
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:
```sh
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:
```sh
SPEC="{ \"openapi\": \"3.0.0\" }"
```
### Docker-Compose
#### .env file example encoding
```sh
SUPPORTED_SUBMIT_METHODS=['get', 'post']
URLS=[ { url: 'https://petstore.swagger.io/v2/swagger.json', name: 'Petstore' } ]
```

60
frontend/web/api-doc/docs/usage/cors.md Normal file
View File

@ -0,0 +1,60 @@
# CORS
CORS is a technique to prevent websites from doing bad things with your personal data. Most browsers + JavaScript toolkits not only support CORS but enforce it, which has implications for your API server which supports Swagger.
You can read about CORS here: http://www.w3.org/TR/cors.
There are two cases where no action is needed for CORS support:
1. Swagger UI is hosted on the same server as the application itself (same host *and* port).
2. The application is located behind a proxy that enables the required CORS headers. This may already be covered within your organization.
Otherwise, CORS support needs to be enabled for:
1. Your Swagger docs. For Swagger 2.0 it's the `swagger.json`/`swagger.yaml` and any externally `$ref`ed docs.
2. For the `Try it now` button to work, CORS needs to be enabled on your API endpoints as well.
### Testing CORS Support
You can verify CORS support with one of three techniques:
- Curl your API and inspect the headers. For instance:
```bash
$ curl -I "https://petstore.swagger.io/v2/swagger.json"
HTTP/1.1 200 OK
Date: Sat, 31 Jan 2015 23:05:44 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, DELETE, PUT, PATCH, OPTIONS
Access-Control-Allow-Headers: Content-Type, api_key, Authorization
Content-Type: application/json
Content-Length: 0
```
This tells us that the petstore resource listing supports OPTIONS, and the following headers: `Content-Type`, `api_key`, `Authorization`.
- Try Swagger UI from your file system and look at the debug console. If CORS is not enabled, you'll see something like this:
```
XMLHttpRequest cannot load http://sad.server.com/v2/api-docs. No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'null' is therefore not allowed access.
```
Swagger UI cannot easily show this error state.
- Use the https://www.test-cors.org website to verify CORS support. Keep in mind this will show a successful result even if `Access-Control-Allow-Headers` is not available, which is still required for Swagger UI to function properly.
### Enabling CORS
The method of enabling CORS depends on the server and/or framework you use to host your application. https://enable-cors.org provides information on how to enable CORS in some common web servers.
Other servers/frameworks may provide you information on how to enable it specifically in their use case.
### CORS and Header Parameters
Swagger UI lets you easily send headers as parameters to requests. The name of these headers *MUST* be supported in your CORS configuration as well. From our example above:
```
Access-Control-Allow-Headers: Content-Type, api_key, Authorization
```
Only headers with these names will be allowed to be sent by Swagger UI.

36
frontend/web/api-doc/docs/usage/deep-linking.md Normal file
View File

@ -0,0 +1,36 @@
# `deepLinking` parameter
Swagger UI allows you to deeply link into tags and operations within a spec. When Swagger UI is provided a URL fragment at runtime, it will automatically expand and scroll to a specified tag or operation.
## Usage
👉🏼 Add `deepLinking: true` to your Swagger UI configuration to enable this functionality. This is demonstrated in [`dist/index.html`](https://github.com/swagger-api/swagger-ui/blob/master/dist/index.html).
When you expand a tag or operation, Swagger UI will automatically update its URL fragment with a deep link to the item.
Conversely, when you collapse a tag or operation, Swagger UI will clear the URL fragment.
You can also right-click a tag name or operation path to copy a link to that tag or operation.
#### Fragment format
The fragment is formatted in one of two ways:
- `#/{tagName}`, to trigger the focus of a specific tag
- `#/{tagName}/{operationId}`, to trigger the focus of a specific operation within a tag
`operationId` is the explicit operationId provided in the spec, if one exists.
Otherwise, Swagger UI generates an implicit operationId by combining the operation's path and method, while escaping non-alphanumeric characters.
## FAQ
> I'm using Swagger UI in an application that needs control of the URL fragment. How do I disable deep-linking?
This functionality is disabled by default, but you can pass `deepLinking: false` into Swagger UI as a configuration item to be sure.
> Can I link to multiple tags or operations?
No, this is not supported.
> Can I collapse everything except the operation or tag I'm linking to?
Sure - use `docExpansion: none` to collapse all tags and operations. Your deep link will take precedence over the setting, so only the tag or operation you've specified will be expanded.

178
frontend/web/api-doc/docs/usage/installation.md Normal file
View File

@ -0,0 +1,178 @@
# Installation
## Distribution channels
### NPM Registry
We publish three modules to npm: **`swagger-ui`**, **`swagger-ui-dist`** and **`swagger-ui-react`**.
**`swagger-ui`** is meant for consumption by JavaScript web projects that include module bundlers,
such as Webpack, Browserify, and Rollup. Its main file exports Swagger UI's main function,
and the module also includes a namespaced stylesheet at `swagger-ui/dist/swagger-ui.css`. Here's an example:
```javascript
import SwaggerUI from 'swagger-ui'
// or use require if you prefer
const SwaggerUI = require('swagger-ui')
SwaggerUI({
dom_id: '#myDomId'
})
```
See the [Webpack Getting Started](../samples/webpack-getting-started) sample for details.
In contrast, **`swagger-ui-dist`** is meant for server-side projects that need assets to serve to clients. The module, when imported, includes an `absolutePath` helper function that returns the absolute filesystem path to where the `swagger-ui-dist` module is installed.
_Note: we suggest using `swagger-ui` when your tooling makes it possible, as `swagger-ui-dist`
will result in more code going across the wire._
The module's contents mirror the `dist` folder you see in the Git repository. The most useful file is `swagger-ui-bundle.js`, which is a build of Swagger UI that includes all the code it needs to run in one file. The folder also has an `index.html` asset, to make it easy to serve Swagger UI like so:
```javascript
const express = require('express')
const pathToSwaggerUi = require('swagger-ui-dist').absolutePath()
const app = express()
app.use(express.static(pathToSwaggerUi))
app.listen(3000)
```
The module also exports `SwaggerUIBundle` and `SwaggerUIStandalonePreset`, so
if you're in a JavaScript project that can't handle a traditional npm module,
you could do something like this:
```js
var SwaggerUIBundle = require('swagger-ui-dist').SwaggerUIBundle
const ui = SwaggerUIBundle({
url: "https://petstore.swagger.io/v2/swagger.json",
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
],
layout: "StandaloneLayout"
})
```
`SwaggerUIBundle` is equivalent to `SwaggerUI`.
### Docker
You can pull a pre-built docker image of the swagger-ui directly from Docker Hub:
```
docker pull swaggerapi/swagger-ui
docker run -p 80:8080 swaggerapi/swagger-ui
```
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
```
You can also provide a URL to a swagger.json on an external host:
```
docker run -p 80:8080 -e SWAGGER_JSON_URL=https://petstore3.swagger.io/api/v3/openapi.json swaggerapi/swagger-ui
```
The base URL of the web application can be changed by specifying the `BASE_URL` environment variable:
```
docker run -p 80:8080 -e BASE_URL=/swagger -e SWAGGER_JSON=/foo/swagger.json -v /bar:/foo swaggerapi/swagger-ui
```
This will serve Swagger UI at `/swagger` instead of `/`.
For more information on controlling Swagger UI through the Docker image, see the Docker section of the [Configuration documentation](configuration.md#docker).
### unpkg
You can embed Swagger UI's code directly in your HTML by using [unpkg's](https://unpkg.com/) interface:
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta
name="description"
content="SwaggerUI"
/>
<title>SwaggerUI</title>
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-bundle.js" crossorigin></script>
<script>
window.onload = () => {
window.ui = SwaggerUIBundle({
url: 'https://petstore3.swagger.io/api/v3/openapi.json',
dom_id: '#swagger-ui',
});
};
</script>
</body>
</html>
```
Using `StandalonePreset` will render `TopBar` and `ValidatorBadge` as well.
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta
name="description"
content="SwaggerUI"
/>
<title>SwaggerUI</title>
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-bundle.js" crossorigin></script>
<script src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-standalone-preset.js" crossorigin></script>
<script>
window.onload = () => {
window.ui = SwaggerUIBundle({
url: 'https://petstore3.swagger.io/api/v3/openapi.json',
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
layout: "StandaloneLayout",
});
};
</script>
</body>
</html>
```
See [unpkg's main page](https://unpkg.com/) for more information on how to use unpkg.
### Static files without HTTP or HTML
Once swagger-ui has successfully generated the `/dist` directory, you can copy this to your own file system and host from there.
## Plain old HTML/CSS/JS (Standalone)
The folder `/dist` includes all the HTML, CSS and JS files needed to run SwaggerUI on a static website or CMS, without requiring NPM.
1. Download the [latest release](https://github.com/swagger-api/swagger-ui/releases/latest).
1. Copy the contents of the `/dist` folder to your server.
1. Open `swagger-initializer.js` in your text editor and replace "https://petstore.swagger.io/v2/swagger.json" with the URL for your OpenAPI 3.0 spec.

38
frontend/web/api-doc/docs/usage/limitations.md Normal file
View File

@ -0,0 +1,38 @@
# Limitations
### Forbidden header names
Some header names cannot be controlled by web applications, due to security
features built into web browsers.
Forbidden headers include:
> - Accept-Charset
> - Accept-Encoding
> - Access-Control-Request-Headers
> - Access-Control-Request-Method
> - Connection
> - Content-Length
> - Cookie
> - Cookie2
> - Date
> - DNT
> - Expect
> - Host
> - Keep-Alive
> - Origin
> - Proxy-*
> - Sec-*
> - Referer
> - TE
> - Trailer
> - Transfer-Encoding
> - Upgrade
> - Via
>
> _[Forbidden header names (developer.mozilla.org)](https://developer.mozilla.org/en-US/docs/Glossary/Forbidden_header_name)_
The biggest impact of this is that OpenAPI 3.0 Cookie parameters cannot be
controlled when running Swagger UI in a browser.
For more context, see [#3956](https://github.com/swagger-api/swagger-ui/issues/3956).

31
frontend/web/api-doc/docs/usage/oauth2.md Normal file
View File

@ -0,0 +1,31 @@
# OAuth 2.0 configuration
You can configure OAuth 2.0 authorization by calling the `initOAuth` method.
Property name | Docker variable | Description
--- | --- | ------
clientId | `OAUTH_CLIENT_ID` | Default clientId. MUST be a string
clientSecret | `OAUTH_CLIENT_SECRET` | **🚨 Never use this parameter in your production environment. It exposes crucial security information. This feature is intended for dev/test environments only. 🚨** <br>Default clientSecret. MUST be a string
realm | `OAUTH_REALM` |realm query parameter (for oauth1) added to `authorizationUrl` and `tokenUrl`. MUST be a string
appName | `OAUTH_APP_NAME` |application name, displayed in authorization popup. MUST be a string
scopeSeparator | `OAUTH_SCOPE_SEPARATOR` |scope separator for passing scopes, encoded before calling, default value is a space (encoded value `%20`). MUST be a string
scopes | `OAUTH_SCOPES` |string array or scope separator (i.e. space) separated string of initially selected oauth scopes, default is empty array
additionalQueryStringParams | `OAUTH_ADDITIONAL_PARAMS` |Additional query parameters added to `authorizationUrl` and `tokenUrl`. MUST be an object
useBasicAuthenticationWithAccessCodeGrant | `OAUTH_USE_BASIC_AUTH` |Only activated for the `accessCode` flow. During the `authorization_code` request to the `tokenUrl`, pass the [Client Password](https://tools.ietf.org/html/rfc6749#section-2.3.1) using the HTTP Basic Authentication scheme (`Authorization` header with `Basic base64encode(client_id + client_secret)`). The default is `false`
usePkceWithAuthorizationCodeGrant | `OAUTH_USE_PKCE` | Only applies to `Authorization Code` flows. [Proof Key for Code Exchange](https://tools.ietf.org/html/rfc7636) brings enhanced security for OAuth public clients. The default is `false` <br/><br/>_Note:_ This option does not hide the client secret input because [neither PKCE nor client secrets are replacements for each other](https://oauth.net/2/pkce/).
```javascript
const ui = SwaggerUI({...})
// Method can be called in any place after calling constructor SwaggerUIBundle
ui.initOAuth({
clientId: "your-client-id",
clientSecret: "your-client-secret-if-required",
realm: "your-realms",
appName: "your-app-name",
scopeSeparator: " ",
scopes: "openid profile",
additionalQueryStringParams: {test: "hello"},
useBasicAuthenticationWithAccessCodeGrant: true,
usePkceWithAuthorizationCodeGrant: true
})
```

54
frontend/web/api-doc/docs/usage/version-detection.md Normal file
View File

@ -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](/docs/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 `JSON.stringify(versions)` in the console and execute the call.
- The result should look 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](/docs/images/swagger-ui2.png)
Some distinct identifiers to Swagger UI 2.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 https://swagger.io
* @license Apache-2.0
*/
```