5.9 KiB
Configuração da Operação de Rota
Existem vários parâmetros que você pode passar para o seu decorador de operação de rota para configurá-lo.
/// warning | "Aviso"
Observe que esses parâmetros são passados diretamente para o decorador de operação de rota, não para a sua função de operação de rota.
///
Código de Status da Resposta
Você pode definir o status_code (HTTP) para ser usado na resposta da sua operação de rota.
Você pode passar diretamente o código int, como 404.
Mas se você não se lembrar o que cada código numérico significa, pode usar as constantes de atalho em status:
//// tab | Python 3.8 and above
{!> ../../../docs_src/path_operation_configuration/tutorial001.py!}
////
//// tab | Python 3.9 and above
{!> ../../../docs_src/path_operation_configuration/tutorial001_py39.py!}
////
//// tab | Python 3.10 and above
{!> ../../../docs_src/path_operation_configuration/tutorial001_py310.py!}
////
Esse código de status será usado na resposta e será adicionado ao esquema OpenAPI.
/// note | "Detalhes Técnicos"
Você também poderia usar from starlette import status.
FastAPI fornece o mesmo starlette.status como fastapi.status apenas como uma conveniência para você, o desenvolvedor. Mas vem diretamente do Starlette.
///
Tags
Você pode adicionar tags para sua operação de rota, passe o parâmetro tags com uma list de str (comumente apenas um str):
//// tab | Python 3.8 and above
{!> ../../../docs_src/path_operation_configuration/tutorial002.py!}
////
//// tab | Python 3.9 and above
{!> ../../../docs_src/path_operation_configuration/tutorial002_py39.py!}
////
//// tab | Python 3.10 and above
{!> ../../../docs_src/path_operation_configuration/tutorial002_py310.py!}
////
Eles serão adicionados ao esquema OpenAPI e usados pelas interfaces de documentação automática:
Tags com Enums
Se você tem uma grande aplicação, você pode acabar acumulando várias tags, e você gostaria de ter certeza de que você sempre usa a mesma tag para operações de rota relacionadas.
Nestes casos, pode fazer sentido armazenar as tags em um Enum.
FastAPI suporta isso da mesma maneira que com strings simples:
{!../../../docs_src/path_operation_configuration/tutorial002b.py!}
Resumo e descrição
Você pode adicionar um summary e uma description:
//// tab | Python 3.8 and above
{!> ../../../docs_src/path_operation_configuration/tutorial003.py!}
////
//// tab | Python 3.9 and above
{!> ../../../docs_src/path_operation_configuration/tutorial003_py39.py!}
////
//// tab | Python 3.10 and above
{!> ../../../docs_src/path_operation_configuration/tutorial003_py310.py!}
////
Descrição do docstring
Como as descrições tendem a ser longas e cobrir várias linhas, você pode declarar a descrição da operação de rota na docstring da função e o FastAPI irá lê-la de lá.
Você pode escrever Markdown na docstring, ele será interpretado e exibido corretamente (levando em conta a indentação da docstring).
//// tab | Python 3.8 and above
{!> ../../../docs_src/path_operation_configuration/tutorial004.py!}
////
//// tab | Python 3.9 and above
{!> ../../../docs_src/path_operation_configuration/tutorial004_py39.py!}
////
//// tab | Python 3.10 and above
{!> ../../../docs_src/path_operation_configuration/tutorial004_py310.py!}
////
Ela será usada nas documentações interativas:
Descrição da resposta
Você pode especificar a descrição da resposta com o parâmetro response_description:
//// tab | Python 3.8 and above
{!> ../../../docs_src/path_operation_configuration/tutorial005.py!}
////
//// tab | Python 3.9 and above
{!> ../../../docs_src/path_operation_configuration/tutorial005_py39.py!}
////
//// tab | Python 3.10 and above
{!> ../../../docs_src/path_operation_configuration/tutorial005_py310.py!}
////
/// info | "Informação"
Note que response_description se refere especificamente à resposta, a description se refere à operação de rota em geral.
///
/// check
OpenAPI especifica que cada operação de rota requer uma descrição de resposta.
Então, se você não fornecer uma, o FastAPI irá gerar automaticamente uma de "Resposta bem-sucedida".
///
Depreciar uma operação de rota
Se você precisar marcar uma operação de rota como descontinuada, mas sem removê-la, passe o parâmetro deprecated:
{!../../../docs_src/path_operation_configuration/tutorial006.py!}
Ela será claramente marcada como descontinuada nas documentações interativas:
Verifique como operações de rota descontinuadas e não descontinuadas se parecem:
Resumindo
Você pode configurar e adicionar metadados para suas operações de rota facilmente passando parâmetros para os decoradores de operação de rota.