扩展 OpenAPI¶

在某些情况下，您可能需要修改生成的 OpenAPI 架构。

在本节中，您将了解如何做到这一点。

正常流程¶

正常的 (默认) 流程如下。

一个 FastAPI 应用程序 (实例) 具有一个 .openapi() 方法，该方法应返回 OpenAPI 架构。

作为应用程序对象创建的一部分，为 /openapi.json (或您设置的 openapi_url) 注册了一个 *路径操作*。

它只是返回一个 JSON 响应，其中包含应用程序 .openapi() 方法的结果。

默认情况下，.openapi() 方法会检查 .openapi_schema 属性以查看它是否有内容，并返回它们。

如果没有，它将使用 fastapi.openapi.utils.get_openapi 中的实用程序函数生成它们。

该函数 get_openapi() 接收以下参数

title: OpenAPI 标题，显示在文档中。
version: 您 API 的版本，例如 2.5.0。
openapi_version: 使用的 OpenAPI 规范版本。默认情况下，为最新版本：3.1.0。
summary: API 的简短摘要。
description: 您 API 的描述，可以包含 Markdown，并将在文档中显示。
routes: 路由列表，这些路由是每个注册的 *路径操作*。它们取自 app.routes。

信息

summary 参数在 OpenAPI 3.1.0 及更高版本中可用，受 FastAPI 0.99.0 及更高版本支持。

覆盖默认值¶

使用以上信息，您可以使用相同的实用程序函数生成 OpenAPI 架构，并覆盖您需要的每个部分。

例如，让我们添加 ReDoc 的 OpenAPI 扩展以包含自定义徽标。

正常 FastAPI¶

首先，像往常一样编写所有 **FastAPI** 应用程序

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()


@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]


def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="Custom title",
        version="2.5.0",
        summary="This is a very custom OpenAPI schema",
        description="Here's a longer description of the custom **OpenAPI** schema",
        routes=app.routes,
    )
    openapi_schema["info"]["x-logo"] = {
        "url": "https://fastapi.org.cn/img/logo-margin/logo-teal.png"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema


app.openapi = custom_openapi

生成 OpenAPI 架构¶

然后，在 custom_openapi() 函数中使用相同的实用程序函数生成 OpenAPI 架构

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()


@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]


def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="Custom title",
        version="2.5.0",
        summary="This is a very custom OpenAPI schema",
        description="Here's a longer description of the custom **OpenAPI** schema",
        routes=app.routes,
    )
    openapi_schema["info"]["x-logo"] = {
        "url": "https://fastapi.org.cn/img/logo-margin/logo-teal.png"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema


app.openapi = custom_openapi

修改 OpenAPI 架构¶

现在您可以添加 ReDoc 扩展，在 OpenAPI 架构的 info "对象" 中添加一个自定义 x-logo

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()


@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]


def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="Custom title",
        version="2.5.0",
        summary="This is a very custom OpenAPI schema",
        description="Here's a longer description of the custom **OpenAPI** schema",
        routes=app.routes,
    )
    openapi_schema["info"]["x-logo"] = {
        "url": "https://fastapi.org.cn/img/logo-margin/logo-teal.png"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema


app.openapi = custom_openapi

缓存 OpenAPI 架构¶

您可以使用 .openapi_schema 属性作为 "缓存"，以存储您生成的架构。

这样，您的应用程序就不必每次用户打开 API 文档时都生成架构。

它只会被生成一次，然后相同的缓存架构将用于下一个请求。

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()


@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]


def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="Custom title",
        version="2.5.0",
        summary="This is a very custom OpenAPI schema",
        description="Here's a longer description of the custom **OpenAPI** schema",
        routes=app.routes,
    )
    openapi_schema["info"]["x-logo"] = {
        "url": "https://fastapi.org.cn/img/logo-margin/logo-teal.png"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema


app.openapi = custom_openapi

覆盖方法¶

现在您可以用新函数替换 .openapi() 方法。

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()


@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]


def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="Custom title",
        version="2.5.0",
        summary="This is a very custom OpenAPI schema",
        description="Here's a longer description of the custom **OpenAPI** schema",
        routes=app.routes,
    )
    openapi_schema["info"]["x-logo"] = {
        "url": "https://fastapi.org.cn/img/logo-margin/logo-teal.png"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema


app.openapi = custom_openapi

检查它¶

转到 http://127.0.0.1:8000/redoc 后，您将看到您正在使用自定义徽标 (在本例中，为 **FastAPI** 的徽标)