Skip to content

扩展 OpenAPI

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

在本节中，您将了解如何实现这一点。

正常流程

正常的（默认的）流程如下。

一个 FastAPI 应用程序（实例）有一个 .openapi() 方法，该方法预期返回 OpenAPI 模式。

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

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

默认情况下，.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 应用程序：

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 模式：

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：

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 文档时都不必生成模式。

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

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() 方法。

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 的徽标）：