扩展 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。

Info

参数 summary 在 OpenAPI 3.1.0 及以上版本中可用，由 FastAPI 0.99.0 及以上版本支持。

覆盖默认值¶

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

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

常规 FastAPI¶

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

Python 3.8+

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.tiangolo.com/img/logo-margin/logo-teal.png"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema


app.openapi = custom_openapi

生成 OpenAPI 模式¶

然后，在 custom_openapi() 函数内部，使用相同的实用函数生成 OpenAPI 模式：

Python 3.8+

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.tiangolo.com/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：

Python 3.8+

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.tiangolo.com/img/logo-margin/logo-teal.png"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema


app.openapi = custom_openapi

缓存 OpenAPI 模式¶

您可以使用属性 .openapi_schema 作为“缓存”来存储生成的模式。

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

它只会生成一次，然后相同的缓存模式将用于后续请求。

Python 3.8+

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.tiangolo.com/img/logo-margin/logo-teal.png"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema


app.openapi = custom_openapi

覆盖方法¶

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

Python 3.8+

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.tiangolo.com/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 的徽标）：