自定义文档 UI 静态资源（自托管）¶

API 文档使用Swagger UI和ReDoc，它们都需要一些 JavaScript 和 CSS 文件。

默认情况下，这些文件是从CDN提供的。

但是可以自定义它，您可以设置一个特定的 CDN，或者自己提供这些文件。

JavaScript 和 CSS 的自定义 CDN¶

假设您想使用一个不同的CDN，例如您想使用 https://unpkg.com/。

如果您所在的国家/地区限制某些 URL，这可能会很有用。

禁用自动文档¶

第一步是禁用自动文档，因为默认情况下，它们会使用默认 CDN。

要禁用它们，请在创建 FastAPI 应用时将它们的 URL 设置为 None

Python 3.9+

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 也是类似的……

Python 3.9+

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}"}

提示

swagger_ui_redirect 的*路径操作*是在使用 OAuth2 时的一个辅助工具。

如果您将 API 与 OAuth2 提供商集成，您将能够进行身份验证并使用获得的凭据返回到 API 文档。并使用真实的 OAuth2 身份验证与其进行交互。

Swagger UI 会在后台为您处理，但它需要这个“重定向”助手。

创建一个路径操作来测试它¶

现在，为了能够测试一切是否正常工作，请创建一个*路径操作*

Python 3.9+

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 可能很有用，例如，如果您需要您的应用程序即使在离线、没有开放 Internet 访问或在本地网络中也能继续工作。

在这里，您将看到如何提供这些文件本身，在同一个 FastAPI 应用中，并配置文档以使用它们。

项目文件结构¶

假设您的项目文件结构如下

.
├── app
│   ├── __init__.py
│   ├── main.py

现在创建一个目录来存储这些静态文件。

您的新文件结构可能看起来像这样

.
├── app
│   ├── __init__.py
│   ├── main.py
└── static/

下载文件¶

下载文档所需的静态文件，并将它们放在 static/ 目录中。

您可能可以通过右键单击每个链接并选择类似“链接另存为...”的选项来完成。

Swagger UI 使用文件

而ReDoc使用文件

redoc.standalone.js

之后，您的文件结构可能看起来像

.
├── app
│   ├── __init__.py
│   ├── main.py
└── static
    ├── redoc.standalone.js
    ├── swagger-ui-bundle.js
    └── swagger-ui.css

提供静态文件¶

导入 StaticFiles。
在特定路径上“挂载”一个 StaticFiles() 实例。

Python 3.9+

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

Python 3.9+

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 也是类似的……

Python 3.9+

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}"}

提示

swagger_ui_redirect 的*路径操作*是在使用 OAuth2 时的一个辅助工具。

如果您将 API 与 OAuth2 提供商集成，您将能够进行身份验证并使用获得的凭据返回到 API 文档。并使用真实的 OAuth2 身份验证与其进行交互。

Swagger UI 会在后台为您处理，但它需要这个“重定向”助手。

创建一个路径操作来测试静态文件¶

现在，为了能够测试一切是否正常工作，请创建一个*路径操作*

Python 3.9+

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¶

现在，您应该能够断开 Wi-Fi，通过 http://127.0.0.1:8000/docs 访问您的文档，然后刷新页面。

即使没有互联网，您也能看到您的 API 文档并与之交互。

自定义文档 UI 静态资源（自托管）¶

JavaScript 和 CSS 的自定义 CDN¶

禁用自动文档¶

包含自定义文档¶

创建一个*路径操作*来测试它¶

测试它¶

为文档自托管 JavaScript 和 CSS¶

项目文件结构¶

下载文件¶

提供静态文件¶

测试静态文件¶

为静态文件禁用自动文档¶

为静态文件包含自定义文档¶

创建一个*路径操作*来测试静态文件¶

测试静态文件 UI¶

创建一个路径操作来测试它¶

创建一个路径操作来测试静态文件¶