Skip to content

Commit f628921

Browse files
blueswenblueswen
committed
Update doc
1 parent d84a3c3 commit f628921

39 files changed

+879
-85
lines changed

‎demo-mkdocs/docs/demo/build-in-multiple.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Support render multiple Swagger UI
1+
Support render multiple Swagger UI.
22

33
## Markdown
44

@@ -9,7 +9,7 @@ Add two attribute in swagger-ui tag:
99

1010
The Swagger UI with multiple OAS takes the first grouped swagger-ui tag position.
1111

12-
```markdown
12+
```html
1313
<swagger-ui grouped name="Pet Store" src="https://petstore.swagger.io/v2/swagger.json"/>
1414
<swagger-ui grouped name="Sample" src="./openapi-spec/sample.yaml"/>
1515
<swagger-ui grouped name="Sample First" src="./openapi-spec/sample-first.yaml"/>

‎demo-mkdocs/docs/demo/multiple.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ Support render multiple Swagger UI.
22

33
## Markdown
44

5-
```markdown
5+
```html
66
<swagger-ui src="./openapi-spec/sample.yaml"/>
77
<swagger-ui src="https://petstore.swagger.io/v2/swagger.json"/>
88
```

‎demo-mkdocs/docs/demo/oauth2.md

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
Support configure OAuth 2.0 authorization by setting attributes for [initOAuth](https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/) method.
2+
3+
| Attribute | Description |
4+
|-------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
5+
| clientId | Default clientId. |
6+
| clientSecret | Default clientSecret.<br>**🚨 Never use this parameter in your production environment. It exposes crucial security information. This feature is intended for dev/test environments only. 🚨** |
7+
| realm | Realm query parameter (for oauth1) added to **authorizationUrl** and **tokenUrl**. |
8+
| appName | Application name, displayed in authorization popup. |
9+
| scopes | Scope space separated string of initially selected oauth scopes, e.g. "openid profile", default is empty. |
10+
| additionalQueryStringParams | Additional query parameters were added to **authorizationUrl** and **tokenUrl**, default is empty.<br>MUST be a JSON, but could wrap string with single quote when attribute value wrapped with double quote, e.g. ```additionalQueryStringParams="{'test': 'hello'}"```, ```additionalQueryStringParams='{"test": "hello"}'``` |
11+
| useBasicAuthenticationWithAccessCodeGrant | 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)**).<br>The default is false, setting true with any case of "true". |
12+
| usePkceWithAuthorizationCodeGrant | Only applies to **authorizationCode** flows. [Proof Key for Code Exchange](https://tools.ietf.org/html/rfc7636) brings enhanced security for OAuth public clients.<br>The default is false, setting true with any case of "true". |
13+
14+
## Markdown
15+
16+
```html
17+
<swagger-ui src="./openapi-spec/sample-oauth2.yaml"
18+
clientId="your-client-id"
19+
clientSecret="your-client-secret-if-required"
20+
realm="your-realms"
21+
appName="your-app-name"
22+
scopes="openid profile"
23+
additionalQueryStringParams="{'test': 'hello'}"
24+
useBasicAuthenticationWithAccessCodeGrant="false"
25+
usePkceWithAuthorizationCodeGrant="false"/>
26+
```
27+
28+
## Swagger UI
29+
30+
<swagger-ui src="./openapi-spec/sample-oauth2.yaml"
31+
clientId="your-client-id"
32+
clientSecret="your-client-secret-if-required"
33+
realm="your-realms"
34+
appName="your-app-name"
35+
scopes="openid profile"
36+
additionalQueryStringParams="{'test': 'hello'}"
37+
useBasicAuthenticationWithAccessCodeGrant="false"
38+
usePkceWithAuthorizationCodeGrant="false"/>

‎demo-mkdocs/docs/demo/openapi-spec/sample-oauth2.yaml

+103
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
openapi: 3.0.2
2+
info:
3+
title: FastAPI
4+
version: 0.1.0
5+
paths:
6+
/token:
7+
post:
8+
summary: Login
9+
operationId: login_token_post
10+
requestBody:
11+
content:
12+
application/x-www-form-urlencoded:
13+
schema:
14+
$ref: '#/components/schemas/Body_login_token_post'
15+
required: true
16+
responses:
17+
'200':
18+
description: Successful Response
19+
content:
20+
application/json:
21+
schema: {}
22+
'422':
23+
description: Validation Error
24+
content:
25+
application/json:
26+
schema:
27+
$ref: '#/components/schemas/HTTPValidationError'
28+
/users/me:
29+
get:
30+
summary: Read Users Me
31+
operationId: read_users_me_users_me_get
32+
responses:
33+
'200':
34+
description: Successful Response
35+
content:
36+
application/json:
37+
schema: {}
38+
security:
39+
- OAuth2PasswordBearer: []
40+
components:
41+
schemas:
42+
Body_login_token_post:
43+
title: Body_login_token_post
44+
required:
45+
- username
46+
- password
47+
type: object
48+
properties:
49+
grant_type:
50+
title: Grant Type
51+
pattern: password
52+
type: string
53+
username:
54+
title: Username
55+
type: string
56+
password:
57+
title: Password
58+
type: string
59+
scope:
60+
title: Scope
61+
type: string
62+
default: ''
63+
client_id:
64+
title: Client Id
65+
type: string
66+
client_secret:
67+
title: Client Secret
68+
type: string
69+
HTTPValidationError:
70+
title: HTTPValidationError
71+
type: object
72+
properties:
73+
detail:
74+
title: Detail
75+
type: array
76+
items:
77+
$ref: '#/components/schemas/ValidationError'
78+
ValidationError:
79+
title: ValidationError
80+
required:
81+
- loc
82+
- msg
83+
- type
84+
type: object
85+
properties:
86+
loc:
87+
title: Location
88+
type: array
89+
items:
90+
type: string
91+
msg:
92+
title: Message
93+
type: string
94+
type:
95+
title: Error Type
96+
type: string
97+
securitySchemes:
98+
OAuth2PasswordBearer:
99+
type: oauth2
100+
flows:
101+
password:
102+
scopes: {}
103+
tokenUrl: token

‎demo-mkdocs/docs/demo/static-file.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ Support using local OpenAPI Specification file on website.
22

33
## Markdown
44

5-
```markdown
5+
```html
66
<swagger-ui src="./openapi-spec/sample.yaml"/>
77
```
88

‎demo-mkdocs/docs/index.md

+4-3
Original file line numberDiff line numberDiff line change
@@ -9,13 +9,14 @@ A MkDocs plugin supports for add [Swagger UI](https://github.com/swagger-api/swa
99
3. Synchronized dark mode with [mkdocs-material](https://squidfunk.github.io/mkdocs-material/)
1010
4. Configure [Swagger UI configuration](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/) through plugin options and tag attributes
1111
5. Support multiple OAS in single Swagger UI with top bar selector
12+
6. Support Swagger UI [initOAuth](https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/) method
1213

1314
## Dependency
1415

1516
1. Python Package
16-
1. beautifulsoup4==4.11.1
17+
1. beautifulsoup4>=4.11.1
1718
2. [Swagger UI dist](https://www.npmjs.com/package/swagger-ui-dist) javascript file and css file
18-
1. swagger-ui-dist==4.12.0
19+
1. swagger-ui-dist>=4.13.0
1920

2021
## Usage
2122

@@ -33,7 +34,7 @@ A MkDocs plugin supports for add [Swagger UI](https://github.com/swagger-api/swa
3334
```
3435
3. Add ```swagger-ui``` tag in markdown to include Swagger UI
3536

36-
```markdown
37+
```html
3738
<swagger-ui src="https://petstore.swagger.io/v2/swagger.json"/>
3839
```
3940

‎demo-mkdocs/docs/options.md

+12-2
Original file line numberDiff line numberDiff line change
@@ -31,12 +31,22 @@ plugins:
3131
## Through tag attributes
3232
3333
```html
34-
<swagger-ui supportedSubmitMethods="['get']" docExpansion="none" filter="" syntaxHighlightTheme="monokai" src="./demo/openapi-spec/sample.yaml"/>
34+
<swagger-ui supportedSubmitMethods="['get']"
35+
docExpansion="none"
36+
filter=""
37+
syntaxHighlightTheme="monokai"
38+
src="./demo/openapi-spec/sample.yaml"/>
3539
```
3640

41+
Tag attributes also supports setting [initOAuth](https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/) method.
42+
3743
### Swagger UI with local configurations
3844

39-
<swagger-ui supportedSubmitMethods="['get']" docExpansion="none" filter="" syntaxHighlightTheme="monokai" src="./demo/openapi-spec/sample.yaml"/>
45+
<swagger-ui supportedSubmitMethods="['get']"
46+
docExpansion="none"
47+
filter=""
48+
syntaxHighlightTheme="monokai"
49+
src="./demo/openapi-spec/sample.yaml"/>
4050

4151
### Swagger UI without local configurations
4252

‎demo-mkdocs/docs/pet-store.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
## Markdown
22

3-
```markdown
3+
```html
44
<swagger-ui src="https://petstore.swagger.io/v2/swagger.json"/>
55
```
66

‎demo-mkdocs/mkdocs.yml

+1
Original file line numberDiff line numberDiff line change
@@ -59,3 +59,4 @@ nav:
5959
- Static File: demo/static-file.md
6060
- Multiple: demo/multiple.md
6161
- Build-in Multiple: demo/build-in-multiple.md
62+
- OAuth2 Initialization: demo/oauth2.md

‎docs/404.html

+24-3
Original file line numberDiff line numberDiff line change
@@ -12,15 +12,15 @@
1212

1313

1414
<link rel="icon" href="/mkdocs-swagger-ui-tag/assets/images/favicon.png">
15-
<meta name="generator" content="mkdocs-1.3.0, mkdocs-material-8.3.9+insiders-4.20.1">
15+
<meta name="generator" content="mkdocs-1.3.0, mkdocs-material-8.3.9+insiders-4.21.0">
1616

1717

1818

1919
<title>MkDocs Swagger UI Tag</title>
2020

2121

2222

23-
<link rel="stylesheet" href="/mkdocs-swagger-ui-tag/assets/stylesheets/main.19db47b7.min.css">
23+
<link rel="stylesheet" href="/mkdocs-swagger-ui-tag/assets/stylesheets/main.846d444e.min.css">
2424

2525

2626
<link rel="stylesheet" href="/mkdocs-swagger-ui-tag/assets/stylesheets/palette.cbb835fc.min.css">
@@ -86,6 +86,8 @@
8686

8787

8888

89+
90+
8991
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
9092
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
9193
<label class="md-overlay" for="__drawer"></label>
@@ -384,6 +386,25 @@
384386

385387

386388

389+
390+
391+
392+
393+
394+
<li class="md-nav__item">
395+
<a href="/mkdocs-swagger-ui-tag/demo/oauth2/" class="md-nav__link">
396+
397+
398+
<span class="md-ellipsis">
399+
OAuth2 Initialization
400+
</span>
401+
402+
</a>
403+
</li>
404+
405+
406+
407+
387408
</ul>
388409
</nav>
389410

@@ -438,7 +459,7 @@ <h1>404 - Not found</h1>
438459
<script id="__config" type="application/json">{"base": "/mkdocs-swagger-ui-tag/", "features": ["toc.integrate"], "search": "/mkdocs-swagger-ui-tag/assets/javascripts/workers/search.720157f5.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.config.lang": "en", "search.config.pipeline": "stopWordFilter", "search.config.separator": "[\\s\\-]+", "search.placeholder": "Search", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version.title": "Select version"}}</script>
439460

440461

441-
<script src="/mkdocs-swagger-ui-tag/assets/javascripts/bundle.5e3df397.min.js"></script>
462+
<script src="/mkdocs-swagger-ui-tag/assets/javascripts/bundle.15234abc.min.js"></script>
442463

443464

444465
</body>

‎docs/assets/javascripts/bundle.15234abc.min.js

+3
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/assets/javascripts/bundle.5e3df397.min.js

-3
This file was deleted.

‎docs/assets/javascripts/swagger-ui-bundle.js

+1-1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/assets/javascripts/swagger-ui-bundle.js.map

+1-1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/assets/javascripts/swagger-ui-standalone-preset.js

+1-1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/assets/javascripts/swagger-ui-standalone-preset.js.map

+1-1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/assets/stylesheets/main.19db47b7.min.css

-1
This file was deleted.

‎docs/assets/stylesheets/main.846d444e.min.css

+1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/assets/stylesheets/swagger-ui.css

+1-1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/assets/stylesheets/swagger-ui.css.map

+1-1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)