扩展 OpenAPI¶
在某些情况下，您可能需要修改生成的 OpenAPI schema。
在本节中，您将看到如何操作。
正常流程¶
正常（默认）的流程如下。
一个 FastAPI 应用程序（实例）有一个 .openapi() 方法，该方法应返回 OpenAPI schema。
在创建应用程序对象时，会为 /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 schema，并覆盖您需要的每个部分。
例如，让我们添加 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 schema¶
然后，在一个 custom_openapi() 函数内部，使用相同的工具函数来生成 OpenAPI schema
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 schema¶
现在您可以添加 ReDoc 扩展，在 OpenAPI schema 的 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 schema¶
您可以使用属性 .openapi_schema 作为“缓存”来存储您生成的 schema。
这样，您的应用程序就不必在每次用户打开您的 API 文档时都生成 schema。
它只会被生成一次，然后对于接下来的请求将使用相同的缓存 schema。
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 的徽标）
