扩展 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。
信息
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 模式¶
现在，你可以通过向 OpenAPI 模式中的 info "对象" 添加自定义的 x-logo 来添加 ReDoc 扩展
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 的徽标）
