Extendendo o OpenAPI¶
Existem alguns casos em que pode ser necessário modificar o esquema OpenAPI gerado.
Nesta seção, você verá como fazer isso.
O processo normal¶
O processo normal (padrão) é o seguinte:
Uma aplicação (instância) do FastAPI possui um método .openapi() que deve retornar o esquema OpenAPI.
Como parte da criação do objeto de aplicação, uma operação de rota para /openapi.json (ou para o que você definir como openapi_url) é registrada.
Ela apenas retorna uma resposta JSON com o resultado do método .openapi() da aplicação.
Por padrão, o que o método .openapi() faz é verificar se a propriedade .openapi_schema tem conteúdo e retorná-lo.
Se não tiver, ele gera o conteúdo usando a função utilitária em fastapi.openapi.utils.get_openapi.
E essa função get_openapi() recebe como parâmetros:
title: O título do OpenAPI, exibido na documentação.version: A versão da sua API, por exemplo,2.5.0.openapi_version: A versão da especificação OpenAPI utilizada. Por padrão, a mais recente:3.1.0.summary: Um resumo curto da API.description: A descrição da sua API, que pode incluir markdown e será exibida na documentação.routes: Uma lista de rotas, que são cada uma das operações de rota registradas. Elas são obtidas deapp.routes.
Informação
O parâmetro summary está disponível no OpenAPI 3.1.0 e superior, suportado pelo FastAPI 0.99.0 e superior.
Sobrescrevendo os padrões¶
Com as informações acima, você pode usar a mesma função utilitária para gerar o esquema OpenAPI e sobrescrever cada parte que precisar.
Por exemplo, vamos adicionar Extensão OpenAPI do ReDoc para incluir um logo personalizado.
FastAPI Normal¶
Primeiro, escreva toda a sua aplicação FastAPI normalmente:
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
Gerar o esquema OpenAPI¶
Em seguida, use a mesma função utilitária para gerar o esquema OpenAPI, dentro de uma função custom_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
Modificar o esquema OpenAPI¶
Agora, você pode adicionar a extensão do ReDoc, incluindo um x-logo personalizado ao "objeto" info no esquema 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
Armazenar em cache o esquema OpenAPI¶
Você pode usar a propriedade .openapi_schema como um "cache" para armazenar o esquema gerado.
Dessa forma, sua aplicação não precisará gerar o esquema toda vez que um usuário abrir a documentação da sua API.
Ele será gerado apenas uma vez, e o mesmo esquema armazenado em cache será utilizado nas próximas requisições.
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
Sobrescrever o método¶
Agora, você pode substituir o método .openapi() pela sua nova função.
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
Verificar¶
Uma vez que você acessar http://127.0.0.1:8000/redoc, verá que está usando seu logo personalizado (neste exemplo, o logo do FastAPI):
