OpenAPI docs¶
用于处理 OpenAPI 自动 UI 文档的实用工具，包括 Swagger UI（默认位于 /docs）和 ReDoc（默认位于 /redoc）。
get_swagger_ui_html(
*,
openapi_url,
title,
swagger_js_url="https://cdn.jsdelivr.net.cn/npm/swagger-ui-dist@5/swagger-ui-bundle.js",
swagger_css_url="https://cdn.jsdelivr.net.cn/npm/swagger-ui-dist@5/swagger-ui.css",
swagger_favicon_url="https://fastapi.org.cn/img/favicon.png",
oauth2_redirect_url=None,
init_oauth=None,
swagger_ui_parameters=None
)
生成并返回用于加载交互式 API 文档（通常在 /docs 处提供）的 Swagger UI HTML。
只有在需要覆盖某些部分（例如用于加载 Swagger UI 的 JavaScript 和 CSS 的 URL）时，你才需要自己调用此函数。
更多信息请阅读 FastAPI 配置 Swagger UI 文档 以及 FastAPI 自定义文档 UI 静态资源（自托管）文档。
| 参数 | 描述 |
|---|---|
openapi_url
|
Swagger UI 应加载和使用的 OpenAPI URL。 这通常由 FastAPI 使用默认 URL 更多信息请阅读 FastAPI 条件 OpenAPI 文档
类型: |
title
|
HTML 更多信息请阅读 FastAPI 自定义文档 UI 静态资源文档
类型: |
swagger_js_url
|
类型: |
swagger_css_url
|
类型: |
swagger_favicon_url
|
要使用的 favicon URL。它通常显示在浏览器标签页中。
类型: |
oauth2_redirect_url
|
OAuth2 重定向 URL，它通常由 FastAPI 自动处理。 更多信息请阅读 FastAPI 自定义文档 UI 静态资源文档
类型： |
init_oauth
|
包含 Swagger UI OAuth2 初始化配置的字典。 更多关于可用配置选项的信息，请参阅 Swagger UI 文档。
类型： |
swagger_ui_parameters
|
类型： |
源代码位于 fastapi/openapi/docs.py
def get_swagger_ui_html(
*,
openapi_url: Annotated[
str,
Doc(
"""
The OpenAPI URL that Swagger UI should load and use.
This is normally done automatically by FastAPI using the default URL
`/openapi.json`.
Read more about it in the
[FastAPI docs for Conditional OpenAPI](https://fastapi.org.cn/how-to/conditional-openapi/#conditional-openapi-from-settings-and-env-vars)
"""
),
],
title: Annotated[
str,
Doc(
"""
The HTML `<title>` content, normally shown in the browser tab.
Read more about it in the
[FastAPI docs for Custom Docs UI Static Assets](https://fastapi.org.cn/how-to/custom-docs-ui-assets/)
"""
),
],
swagger_js_url: Annotated[
str,
Doc(
"""
The URL to use to load the Swagger UI JavaScript.
It is normally set to a CDN URL.
Read more about it in the
[FastAPI docs for Custom Docs UI Static Assets](https://fastapi.org.cn/how-to/custom-docs-ui-assets/)
"""
),
] = "https://cdn.jsdelivr.net.cn/npm/swagger-ui-dist@5/swagger-ui-bundle.js",
swagger_css_url: Annotated[
str,
Doc(
"""
The URL to use to load the Swagger UI CSS.
It is normally set to a CDN URL.
Read more about it in the
[FastAPI docs for Custom Docs UI Static Assets](https://fastapi.org.cn/how-to/custom-docs-ui-assets/)
"""
),
] = "https://cdn.jsdelivr.net.cn/npm/swagger-ui-dist@5/swagger-ui.css",
swagger_favicon_url: Annotated[
str,
Doc(
"""
The URL of the favicon to use. It is normally shown in the browser tab.
"""
),
] = "https://fastapi.org.cn/img/favicon.png",
oauth2_redirect_url: Annotated[
str | None,
Doc(
"""
The OAuth2 redirect URL, it is normally automatically handled by FastAPI.
Read more about it in the
[FastAPI docs for Custom Docs UI Static Assets](https://fastapi.org.cn/how-to/custom-docs-ui-assets/)
"""
),
] = None,
init_oauth: Annotated[
dict[str, Any] | None,
Doc(
"""
A dictionary with Swagger UI OAuth2 initialization configurations.
Read more about the available configuration options in the
[Swagger UI docs](https://swagger.org.cn/docs/open-source-tools/swagger-ui/usage/oauth2/).
"""
),
] = None,
swagger_ui_parameters: Annotated[
dict[str, Any] | None,
Doc(
"""
Configuration parameters for Swagger UI.
It defaults to [swagger_ui_default_parameters][fastapi.openapi.docs.swagger_ui_default_parameters].
Read more about it in the
[FastAPI docs about how to Configure Swagger UI](https://fastapi.org.cn/how-to/configure-swagger-ui/).
"""
),
] = None,
) -> HTMLResponse:
"""
Generate and return the HTML that loads Swagger UI for the interactive
API docs (normally served at `/docs`).
You would only call this function yourself if you needed to override some parts,
for example the URLs to use to load Swagger UI's JavaScript and CSS.
Read more about it in the
[FastAPI docs for Configure Swagger UI](https://fastapi.org.cn/how-to/configure-swagger-ui/)
and the [FastAPI docs for Custom Docs UI Static Assets (Self-Hosting)](https://fastapi.org.cn/how-to/custom-docs-ui-assets/).
"""
current_swagger_ui_parameters = swagger_ui_default_parameters.copy()
if swagger_ui_parameters:
current_swagger_ui_parameters.update(swagger_ui_parameters)
html = f"""
<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link type="text/css" rel="stylesheet" href="{swagger_css_url}">
<link rel="shortcut icon" href="{swagger_favicon_url}">
<title>{title}</title>
</head>
<body>
<div id="swagger-ui">
</div>
<script src="{swagger_js_url}"></script>
<!-- `SwaggerUIBundle` is now available on the page -->
<script>
const ui = SwaggerUIBundle({{
url: '{openapi_url}',
"""
for key, value in current_swagger_ui_parameters.items():
html += f"{_html_safe_json(key)}: {_html_safe_json(jsonable_encoder(value))},\n"
if oauth2_redirect_url:
html += f"oauth2RedirectUrl: window.location.origin + '{oauth2_redirect_url}',"
html += """
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
],
})"""
if init_oauth:
html += f"""
ui.initOAuth({_html_safe_json(jsonable_encoder(init_oauth))})
"""
html += """
</script>
</body>
</html>
"""
return HTMLResponse(html)
get_redoc_html(
*,
openapi_url,
title,
redoc_js_url="https://cdn.jsdelivr.net.cn/npm/redoc@2/bundles/redoc.standalone.js",
redoc_favicon_url="https://fastapi.org.cn/img/favicon.png",
with_google_fonts=True
)
生成并返回用于加载 ReDoc 的 HTML 响应，以供替代 API 文档（通常在 /redoc 处提供）使用。
只有在需要覆盖某些部分（例如用于加载 ReDoc 的 JavaScript 和 CSS 的 URL）时，你才需要自己调用此函数。
更多信息请阅读 FastAPI 自定义文档 UI 静态资源（自托管）文档。
| 参数 | 描述 |
|---|---|
openapi_url
|
类型: |
title
|
HTML 更多信息请阅读 FastAPI 自定义文档 UI 静态资源文档
类型: |
redoc_js_url
|
类型: |
redoc_favicon_url
|
要使用的 favicon URL。它通常显示在浏览器标签页中。
类型: |
with_google_fonts
|
加载并使用 Google Fonts。
类型: |
源代码位于 fastapi/openapi/docs.py
def get_redoc_html(
*,
openapi_url: Annotated[
str,
Doc(
"""
The OpenAPI URL that ReDoc should load and use.
This is normally done automatically by FastAPI using the default URL
`/openapi.json`.
Read more about it in the
[FastAPI docs for Conditional OpenAPI](https://fastapi.org.cn/how-to/conditional-openapi/#conditional-openapi-from-settings-and-env-vars)
"""
),
],
title: Annotated[
str,
Doc(
"""
The HTML `<title>` content, normally shown in the browser tab.
Read more about it in the
[FastAPI docs for Custom Docs UI Static Assets](https://fastapi.org.cn/how-to/custom-docs-ui-assets/)
"""
),
],
redoc_js_url: Annotated[
str,
Doc(
"""
The URL to use to load the ReDoc JavaScript.
It is normally set to a CDN URL.
Read more about it in the
[FastAPI docs for Custom Docs UI Static Assets](https://fastapi.org.cn/how-to/custom-docs-ui-assets/)
"""
),
] = "https://cdn.jsdelivr.net.cn/npm/redoc@2/bundles/redoc.standalone.js",
redoc_favicon_url: Annotated[
str,
Doc(
"""
The URL of the favicon to use. It is normally shown in the browser tab.
"""
),
] = "https://fastapi.org.cn/img/favicon.png",
with_google_fonts: Annotated[
bool,
Doc(
"""
Load and use Google Fonts.
"""
),
] = True,
) -> HTMLResponse:
"""
Generate and return the HTML response that loads ReDoc for the alternative
API docs (normally served at `/redoc`).
You would only call this function yourself if you needed to override some parts,
for example the URLs to use to load ReDoc's JavaScript and CSS.
Read more about it in the
[FastAPI docs for Custom Docs UI Static Assets (Self-Hosting)](https://fastapi.org.cn/how-to/custom-docs-ui-assets/).
"""
html = f"""
<!DOCTYPE html>
<html>
<head>
<title>{title}</title>
<!-- needed for adaptive design -->
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
"""
if with_google_fonts:
html += """
<link href="https://fonts.googleapis.ac.cn/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
"""
html += f"""
<link rel="shortcut icon" href="{redoc_favicon_url}">
<!--
ReDoc doesn't change outer page styles
-->
<style>
body {{
margin: 0;
padding: 0;
}}
</style>
</head>
<body>
<noscript>
ReDoc requires Javascript to function. Please enable it to browse the documentation.
</noscript>
<redoc spec-url="{openapi_url}"></redoc>
<script src="{redoc_js_url}"> </script>
</body>
</html>
"""
return HTMLResponse(html)
get_swagger_ui_oauth2_redirect_html()
生成带有 Swagger UI OAuth2 重定向的 HTML 响应。
你通常不需要使用或更改此函数。
源代码位于 fastapi/openapi/docs.py
def get_swagger_ui_oauth2_redirect_html() -> HTMLResponse:
"""
Generate the HTML response with the OAuth2 redirection for Swagger UI.
You normally don't need to use or change this.
"""
# copied from https://github.com/swagger-api/swagger-ui/blob/v4.14.0/dist/oauth2-redirect.html
html = """
<!doctype html>
<html lang="en-US">
<head>
<title>Swagger UI: OAuth2 Redirect</title>
</head>
<body>
<script>
'use strict';
function run () {
var oauth2 = window.opener.swaggerUIRedirectOauth2;
var sentState = oauth2.state;
var redirectUrl = oauth2.redirectUrl;
var isValid, qp, arr;
if (/code|token|error/.test(window.location.hash)) {
qp = window.location.hash.substring(1).replace('?', '&');
} else {
qp = location.search.substring(1);
}
arr = qp.split("&");
arr.forEach(function (v,i,_arr) { _arr[i] = '"' + v.replace('=', '":"') + '"';});
qp = qp ? JSON.parse('{' + arr.join() + '}',
function (key, value) {
return key === "" ? value : decodeURIComponent(value);
}
) : {};
isValid = qp.state === sentState;
if ((
oauth2.auth.schema.get("flow") === "accessCode" ||
oauth2.auth.schema.get("flow") === "authorizationCode" ||
oauth2.auth.schema.get("flow") === "authorization_code"
) && !oauth2.auth.code) {
if (!isValid) {
oauth2.errCb({
authId: oauth2.auth.name,
source: "auth",
level: "warning",
message: "Authorization may be unsafe, passed state was changed in server. The passed state wasn't returned from auth server."
});
}
if (qp.code) {
delete oauth2.state;
oauth2.auth.code = qp.code;
oauth2.callback({auth: oauth2.auth, redirectUrl: redirectUrl});
} else {
let oauthErrorMsg;
if (qp.error) {
oauthErrorMsg = "["+qp.error+"]: " +
(qp.error_description ? qp.error_description+ ". " : "no accessCode received from the server. ") +
(qp.error_uri ? "More info: "+qp.error_uri : "");
}
oauth2.errCb({
authId: oauth2.auth.name,
source: "auth",
level: "error",
message: oauthErrorMsg || "[Authorization failed]: no accessCode received from the server."
});
}
} else {
oauth2.callback({auth: oauth2.auth, token: qp, isValid: isValid, redirectUrl: redirectUrl});
}
window.close();
}
if (document.readyState !== 'loading') {
run();
} else {
document.addEventListener('DOMContentLoaded', function () {
run();
});
}
</script>
</body>
</html>
"""
return HTMLResponse(content=html)
module-attribute ¶
swagger_ui_default_parameters = {
"dom_id": "#swagger-ui",
"layout": "BaseLayout",
"deepLinking": True,
"showExtensions": True,
"showCommonExtensions": True,
}
Swagger UI 的默认配置。
你可以将其用作模板，以添加所需的任何其他配置。