自定义文档 UI 静态资源（自托管）¶
API 文档使用 Swagger UI 和 ReDoc，它们各自需要一些 JavaScript 和 CSS 文件。
默认情况下，这些文件通过 CDN 提供。
但可以自定义，你可以设置特定的 CDN，或者自行托管这些文件。
自定义 JavaScript 和 CSS 的 CDN¶
假设你想使用不同的 CDN，例如 https://unpkg.com/。
这可能很有用，例如，如果你所在的国家限制某些 URL。
禁用自动文档¶
第一步是禁用自动文档，因为默认情况下，它们使用默认的 CDN。
要禁用它们，在创建 FastAPI 应用时将其 URL 设置为 None：
from fastapi import FastAPI
from fastapi.openapi.docs import (
get_redoc_html,
get_swagger_ui_html,
get_swagger_ui_oauth2_redirect_html,
)
app = FastAPI(docs_url=None, redoc_url=None)
@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui_html():
return get_swagger_ui_html(
openapi_url=app.openapi_url,
title=app.title + " - Swagger UI",
oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
swagger_js_url="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js",
swagger_css_url="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css",
)
@app.get(app.swagger_ui_oauth2_redirect_url, include_in_schema=False)
async def swagger_ui_redirect():
return get_swagger_ui_oauth2_redirect_html()
@app.get("/redoc", include_in_schema=False)
async def redoc_html():
return get_redoc_html(
openapi_url=app.openapi_url,
title=app.title + " - ReDoc",
redoc_js_url="https://unpkg.com/redoc@2/bundles/redoc.standalone.js",
)
@app.get("/users/{username}")
async def read_user(username: str):
return {"message": f"Hello {username}"}
包含自定义文档¶
现在你可以为自定义文档创建 路径操作。
你可以重用 FastAPI 的内部函数来创建文档的 HTML 页面，并传递所需的参数：
openapi_url：文档 HTML 页面可以获取 API 的 OpenAPI 模式的 URL。你可以在这里使用属性app.openapi_url。title：你的 API 的标题。oauth2_redirect_url：你可以在这里使用app.swagger_ui_oauth2_redirect_url来使用默认值。swagger_js_url：Swagger UI 文档 HTML 可以获取 JavaScript 文件的 URL。这是自定义 CDN URL。swagger_css_url：Swagger UI 文档 HTML 可以获取 CSS 文件的 URL。这是自定义 CDN URL。
ReDoc 类似...
from fastapi import FastAPI
from fastapi.openapi.docs import (
get_redoc_html,
get_swagger_ui_html,
get_swagger_ui_oauth2_redirect_html,
)
app = FastAPI(docs_url=None, redoc_url=None)
@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui_html():
return get_swagger_ui_html(
openapi_url=app.openapi_url,
title=app.title + " - Swagger UI",
oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
swagger_js_url="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js",
swagger_css_url="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css",
)
@app.get(app.swagger_ui_oauth2_redirect_url, include_in_schema=False)
async def swagger_ui_redirect():
return get_swagger_ui_oauth2_redirect_html()
@app.get("/redoc", include_in_schema=False)
async def redoc_html():
return get_redoc_html(
openapi_url=app.openapi_url,
title=app.title + " - ReDoc",
redoc_js_url="https://unpkg.com/redoc@2/bundles/redoc.standalone.js",
)
@app.get("/users/{username}")
async def read_user(username: str):
return {"message": f"Hello {username}"}
Tip
swagger_ui_redirect 的 路径操作 是使用 OAuth2 时的辅助工具。
如果你将 API 与 OAuth2 提供者集成，你将能够进行身份验证并返回到 API 文档，使用获取的凭据。并使用真实的 OAuth2 身份验证与之交互。
Swagger UI 会在后台为你处理，但它需要这个“重定向”辅助工具。
创建 路径操作 进行测试¶
现在，为了测试一切是否正常，创建一个 路径操作：
from fastapi import FastAPI
from fastapi.openapi.docs import (
get_redoc_html,
get_swagger_ui_html,
get_swagger_ui_oauth2_redirect_html,
)
app = FastAPI(docs_url=None, redoc_url=None)
@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui_html():
return get_swagger_ui_html(
openapi_url=app.openapi_url,
title=app.title + " - Swagger UI",
oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
swagger_js_url="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js",
swagger_css_url="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css",
)
@app.get(app.swagger_ui_oauth2_redirect_url, include_in_schema=False)
async def swagger_ui_redirect():
return get_swagger_ui_oauth2_redirect_html()
@app.get("/redoc", include_in_schema=False)
async def redoc_html():
return get_redoc_html(
openapi_url=app.openapi_url,
title=app.title + " - ReDoc",
redoc_js_url="https://unpkg.com/redoc@2/bundles/redoc.standalone.js",
)
@app.get("/users/{username}")
async def read_user(username: str):
return {"message": f"Hello {username}"}
测试¶
现在，你应该能够访问你的文档 http://127.0.0.1:8000/docs，并重新加载页面，它将从新的 CDN 加载这些资源。
自托管文档的 JavaScript 和 CSS¶
自托管 JavaScript 和 CSS 可能很有用，例如，如果你的应用需要在没有开放互联网访问或本地网络中离线工作。
这里你将看到如何自行托管这些文件，在同一个 FastAPI 应用中，并配置文档以使用它们。
项目文件结构¶
假设你的项目文件结构如下：
.
├── app
│ ├── __init__.py
│ ├── main.py
现在创建一个目录来存储这些静态文件。
你的新文件结构可能如下：
.
├── app
│ ├── __init__.py
│ ├── main.py
└── static/
下载文件¶
下载文档所需的静态文件并将其放在 static/ 目录中。
你可能可以右键单击每个链接并选择类似于 另存为... 的选项。
Swagger UI 使用以下文件：
ReDoc 使用以下文件：
之后，你的文件结构可能如下：
.
├── app
│ ├── __init__.py
│ ├── main.py
└── static
├── redoc.standalone.js
├── swagger-ui-bundle.js
└── swagger-ui.css
提供静态文件¶
- 导入
StaticFiles。 - 在特定路径“挂载”一个
StaticFiles()实例。
from fastapi import FastAPI
from fastapi.openapi.docs import (
get_redoc_html,
get_swagger_ui_html,
get_swagger_ui_oauth2_redirect_html,
)
from fastapi.staticfiles import StaticFiles
app = FastAPI(docs_url=None, redoc_url=None)
app.mount("/static", StaticFiles(directory="static"), name="static")
@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui_html():
return get_swagger_ui_html(
openapi_url=app.openapi_url,
title=app.title + " - Swagger UI",
oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
swagger_js_url="/static/swagger-ui-bundle.js",
swagger_css_url="/static/swagger-ui.css",
)
@app.get(app.swagger_ui_oauth2_redirect_url, include_in_schema=False)
async def swagger_ui_redirect():
return get_swagger_ui_oauth2_redirect_html()
@app.get("/redoc", include_in_schema=False)
async def redoc_html():
return get_redoc_html(
openapi_url=app.openapi_url,
title=app.title + " - ReDoc",
redoc_js_url="/static/redoc.standalone.js",
)
@app.get("/users/{username}")
async def read_user(username: str):
return {"message": f"Hello {username}"}
测试静态文件¶
启动你的应用并访问 http://127.0.0.1:8000/static/redoc.standalone.js。
你应该看到一个非常长的 ReDoc JavaScript 文件。
它可能以类似以下内容开头：
/*! For license information please see redoc.standalone.js.LICENSE.txt */
!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t(require("null")):
...
这确认了你能够从应用中提供静态文件，并且你将文档的静态文件放在了正确的位置。
现在我们可以配置应用以使用这些静态文件作为文档。
禁用自动文档以使用静态文件¶
与使用自定义 CDN 时相同，第一步是禁用自动文档，因为它们默认使用 CDN。
要禁用它们，在创建 FastAPI 应用时将其 URL 设置为 None：
from fastapi import FastAPI
from fastapi.openapi.docs import (
get_redoc_html,
get_swagger_ui_html,
get_swagger_ui_oauth2_redirect_html,
)
from fastapi.staticfiles import StaticFiles
app = FastAPI(docs_url=None, redoc_url=None)
app.mount("/static", StaticFiles(directory="static"), name="static")
@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui_html():
return get_swagger_ui_html(
openapi_url=app.openapi_url,
title=app.title + " - Swagger UI",
oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
swagger_js_url="/static/swagger-ui-bundle.js",
swagger_css_url="/static/swagger-ui.css",
)
@app.get(app.swagger_ui_oauth2_redirect_url, include_in_schema=False)
async def swagger_ui_redirect():
return get_swagger_ui_oauth2_redirect_html()
@app.get("/redoc", include_in_schema=False)
async def redoc_html():
return get_redoc_html(
openapi_url=app.openapi_url,
title=app.title + " - ReDoc",
redoc_js_url="/static/redoc.standalone.js",
)
@app.get("/users/{username}")
async def read_user(username: str):
return {"message": f"Hello {username}"}
包含自定义文档以使用静态文件¶
与自定义 CDN 相同的方式，现在你可以为自定义文档创建 路径操作。
同样，你可以重用 FastAPI 的内部函数来创建文档的 HTML 页面，并传递所需的参数：
openapi_url：文档 HTML 页面可以获取 API 的 OpenAPI 模式的 URL。你可以在这里使用属性app.openapi_url。title：你的 API 的标题。oauth2_redirect_url：你可以在这里使用app.swagger_ui_oauth2_redirect_url来使用默认值。swagger_js_url：Swagger UI 文档 HTML 可以获取 JavaScript 文件的 URL。这是你的应用现在提供的文件。swagger_css_url：Swagger UI 文档 HTML 可以获取 CSS 文件的 URL。这是你的应用现在提供的文件。
ReDoc 类似...
from fastapi import FastAPI
from fastapi.openapi.docs import (
get_redoc_html,
get_swagger_ui_html,
get_swagger_ui_oauth2_redirect_html,
)
from fastapi.staticfiles import StaticFiles
app = FastAPI(docs_url=None, redoc_url=None)
app.mount("/static", StaticFiles(directory="static"), name="static")
@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui_html():
return get_swagger_ui_html(
openapi_url=app.openapi_url,
title=app.title + " - Swagger UI",
oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
swagger_js_url="/static/swagger-ui-bundle.js",
swagger_css_url="/static/swagger-ui.css",
)
@app.get(app.swagger_ui_oauth2_redirect_url, include_in_schema=False)
async def swagger_ui_redirect():
return get_swagger_ui_oauth2_redirect_html()
@app.get("/redoc", include_in_schema=False)
async def redoc_html():
return get_redoc_html(
openapi_url=app.openapi_url,
title=app.title + " - ReDoc",
redoc_js_url="/static/redoc.standalone.js",
)
@app.get("/users/{username}")
async def read_user(username: str):
return {"message": f"Hello {username}"}
Tip
swagger_ui_redirect 的 路径操作 是使用 OAuth2 时的辅助工具。
如果你将 API 与 OAuth2 提供者集成，你将能够进行身份验证并返回到 API 文档，使用获取的凭据。并使用真实的 OAuth2 身份验证与之交互。
Swagger UI 会在后台为你处理，但它需要这个“重定向”辅助工具。
创建 路径操作 测试静态文件¶
现在，为了测试一切是否正常，创建一个 路径操作：
from fastapi import FastAPI
from fastapi.openapi.docs import (
get_redoc_html,
get_swagger_ui_html,
get_swagger_ui_oauth2_redirect_html,
)
from fastapi.staticfiles import StaticFiles
app = FastAPI(docs_url=None, redoc_url=None)
app.mount("/static", StaticFiles(directory="static"), name="static")
@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui_html():
return get_swagger_ui_html(
openapi_url=app.openapi_url,
title=app.title + " - Swagger UI",
oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
swagger_js_url="/static/swagger-ui-bundle.js",
swagger_css_url="/static/swagger-ui.css",
)
@app.get(app.swagger_ui_oauth2_redirect_url, include_in_schema=False)
async def swagger_ui_redirect():
return get_swagger_ui_oauth2_redirect_html()
@app.get("/redoc", include_in_schema=False)
async def redoc_html():
return get_redoc_html(
openapi_url=app.openapi_url,
title=app.title + " - ReDoc",
redoc_js_url="/static/redoc.standalone.js",
)
@app.get("/users/{username}")
async def read_user(username: str):
return {"message": f"Hello {username}"}
测试静态文件 UI¶
现在，你应该能够断开 WiFi，访问你的文档 http://127.0.0.1:8000/docs，并重新加载页面。
即使没有互联网，你也能够看到 API 的文档并与之交互。