///
-/// info | Informação
+/// note | Nota
A chave `model` não é parte do OpenAPI.
///
-/// info | Informação
+/// note | Nota
A menos que você especifique um media type diferente explicitamente em seu parâmetro `responses`, o FastAPI assumirá que o retorno possui o mesmo media type contido na classe principal de retorno (padrão `application/json`).
Esse comportamento foi revertido na versão 0.118.0, para que o código de saída após o `yield` seja executado depois que a resposta for enviada.
-/// info | Informação
+/// note | Nota
Como você verá abaixo, isso é muito semelhante ao comportamento antes da versão 0.106.0, mas com várias melhorias e correções de bugs para casos extremos.
Há alguns casos de uso, com condições específicas, que poderiam se beneficiar do comportamento antigo de executar o código de saída das dependências com `yield` antes de enviar a resposta.
-Por exemplo, imagine que você tem código que usa uma sessão de banco de dados em uma dependência com `yield` apenas para verificar um usuário, mas a sessão de banco de dados nunca é usada novamente na *função de operação de rota*, somente na dependência, e a resposta demora a ser enviada, como um `StreamingResponse` que envia dados lentamente, mas por algum motivo não usa o banco de dados.
+Por exemplo, imagine que você tem código que usa uma sessão de banco de dados em uma dependência com `yield` apenas para verificar um usuário, mas a sessão de banco de dados nunca é usada novamente na *função de operação de rota*, somente na dependência, e a response demora a ser enviada, como um `StreamingResponse` que envia dados lentamente, mas por algum motivo não usa o banco de dados.
Nesse caso, a sessão de banco de dados seria mantida até que a resposta termine de ser enviada, mas se você não a usa, então não seria necessário mantê-la.
{* ../../docs_src/custom_response/tutorial002_py310.py hl[2,7] *}
-/// info | Informação
+/// note | Nota
O parâmetro `response_class` também será usado para definir o "media type" da resposta.
///
-/// info | Informação
+/// note | Nota
Obviamente, o cabeçalho `Content-Type`, o código de status, etc, virão do objeto `Response` que você retornou.
Isso funciona da mesma forma que com os modelos Pydantic. E na verdade é alcançado da mesma maneira por baixo dos panos, usando Pydantic.
-/// info | Informação
+/// note | Nota
Lembre-se de que dataclasses não podem fazer tudo o que os modelos Pydantic podem fazer.
Aqui, a função de manipulador do evento `shutdown` escreverá uma linha de texto `"Application shutdown"` no arquivo `log.txt`.
-/// info | Informação
+/// note | Nota
Na função `open()`, o `mode="a"` significa "acrescentar", então a linha será adicionada depois do que já estiver naquele arquivo, sem sobrescrever o conteúdo anterior.
Por baixo, na especificação técnica do ASGI, isso é parte do [Protocolo Lifespan](https://asgi.readthedocs.io/en/latest/specs/lifespan.html), e define eventos chamados `startup` e `shutdown`.
-/// info | Informação
+/// note | Nota
Você pode ler mais sobre os manipuladores de `lifespan` do Starlette na [Documentação do Lifespan do Starlette](https://www.starlette.dev/lifespan/).
Por exemplo, você pode querer experimentar:
* [Stainless](https://www.stainless.com/?utm_source=fastapi&utm_medium=referral)
-* [liblab](https://developers.liblab.com/tutorials/sdk-for-fastapi?utm_source=fastapi)
Algumas dessas soluções também podem ser open source ou oferecer planos gratuitos, para que você possa testá-las sem compromisso financeiro. Outros geradores comerciais de SDK estão disponíveis e podem ser encontrados online. 🤓
Nesse ponto você tem a(s) *operação(ões) de rota de callback* necessária(s) (a(s) que o *desenvolvedor externo* deveria implementar na *API externa*) no roteador de callback que você criou acima.
-Agora use o parâmetro `callbacks` no decorador da *operação de rota da sua API* para passar o atributo `.routes` (que é na verdade apenas uma `list` de rotas/*operações de path*) do roteador de callback:
+Agora use o parâmetro `callbacks` no decorador da *operação de rota da sua API* para passar o atributo `.routes` do roteador de callback:
{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[33] *}
/// tip | Dica
-Perceba que você não está passando o roteador em si (`invoices_callback_router`) para `callback=`, mas o atributo `.routes`, como em `invoices_callback_router.routes`.
+Perceba que você não está passando o roteador em si (`invoices_callback_router`) para `callbacks=`, mas o atributo `.routes`, como em `invoices_callback_router.routes`. O FastAPI usará essas rotas para gerar a documentação OpenAPI do callback.
///
Isto pode facilitar bastante para os seus usuários **implementarem as APIs deles** para receber as requisições dos seus **webhooks**, eles podem inclusive ser capazes de gerar parte do código da API deles.
-/// info | Informação
+/// note | Nota
Webhooks estão disponíveis a partir do OpenAPI 3.1.0, e possui suporte do FastAPI a partir da versão `0.99.0`.
Os webhooks que você define aparecerão no esquema do **OpenAPI** e na **página de documentação** gerada automaticamente.
-/// info | Informação
+/// note | Nota
O objeto `app.webhooks` é na verdade apenas um `APIRouter`, o mesmo tipo que você utilizaria ao estruturar a sua aplicação com diversos arquivos.
### Utilizando o nome da *função de operação de rota* como o operationId { #using-the-path-operation-function-name-as-the-operationid }
-Se você quiser utilizar o nome das funções da sua API como `operationId`s, você pode iterar sobre todos esses nomes e sobrescrever o `operation_id` em cada *operação de rota* utilizando o `APIRoute.name` dela.
+Se você quiser utilizar os nomes das funções da sua API como `operationId`s, você pode passar uma `generate_unique_id_function` personalizada para o `FastAPI`.
-Você deveria fazer isso depois de adicionar todas as suas *operações de rota*.
+A função recebe cada `APIRoute` e retorna o `operationId` a ser usado para aquela operação de rota.
-{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py310.py hl[2, 12:21, 24] *}
-
-/// tip | Dica
-
-Se você chamar `app.openapi()` manualmente, você deveria atualizar os `operationId`s antes dessa chamada.
-
-///
+{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py310.py hl[2,5:6,9] *}
/// warning | Atenção
Você pode retornar uma `Response` ou qualquer subclasse dela.
-/// info | Informação
+/// note | Nota
A própria `JSONResponse` é uma subclasse de `Response`.
* `instagram_basic` é utilizado pelo Facebook / Instagram.
* `https://www.googleapis.com/auth/drive` é utilizado pelo Google.
-/// info | Informação
+/// note | Nota
No OAuth2, um "escopo" é apenas uma string que declara uma permissão específica necessária.
Mas se você quer transmitir dados binários puros ou strings, veja como fazer.
-/// info | Informação
+/// note | Nota
Adicionado no FastAPI 0.134.0.
E, em muitos casos, lê-los seria uma operação bloqueante (que poderia bloquear o loop de eventos), pois são lidos do disco ou da rede.
-/// info | Informação
+/// note | Nota
O exemplo acima é, na verdade, uma exceção, porque o objeto `io.BytesIO` já está em memória, então lê-lo não bloqueará nada.
# Verificação Estrita de Content-Type { #strict-content-type-checking }
-Por padrão, o **FastAPI** usa verificação estrita do cabeçalho `Content-Type` para corpos de requisição JSON; isso significa que requisições JSON devem incluir um `Content-Type` válido (por exemplo, `application/json`) para que o corpo seja interpretado como JSON.
+Por padrão, o **FastAPI** usa verificação estrita do cabeçalho `Content-Type` para corpos de requisição JSON; isso significa que requisições JSON **devem** incluir um `Content-Type` válido (por exemplo, `application/json`) para que o corpo seja interpretado como JSON.
## Risco de CSRF { #csrf-risk }
Usando o frontend, você pode fazer o agente de IA executar ações em seu nome.
-Como está em execução localmente e não na Internet aberta, você decide não configurar autenticação, confiando apenas no acesso à rede local.
+Como está em execução **localmente** e não na Internet aberta, você decide **não configurar autenticação**, confiando apenas no acesso à rede local.
Então um de seus usuários poderia instalá-lo e executá-lo localmente.
Atacantes poderiam simplesmente executar um script para enviar requisições à sua API, sem necessidade de interação do navegador, então você provavelmente já está protegendo quaisquer endpoints privilegiados.
-Nesse caso, esse ataque/risco não se aplica a você.
+Nesse caso, **esse ataque/risco não se aplica a você**.
-Esse risco e ataque é relevante principalmente quando a aplicação roda na rede local e essa é a única proteção presumida.
+Esse risco e ataque é relevante principalmente quando a aplicação roda na **rede local** e essa é a **única proteção presumida**.
## Permitindo Requisições sem Content-Type { #allowing-requests-without-content-type }
Com essa configuração, requisições sem um cabeçalho `Content-Type` terão o corpo interpretado como JSON, o mesmo comportamento das versões mais antigas do FastAPI.
-/// info | Informação
+/// note | Nota
Esse comportamento e configuração foram adicionados no FastAPI 0.132.0.
{* ../../docs_src/websockets_/tutorial002_an_py310.py hl[68:69,82] *}
-/// info | Informação
+/// note | Nota
Como isso é um WebSocket, não faz muito sentido levantar uma `HTTPException`, em vez disso levantamos uma `WebSocketException`.
## Usando `WSGIMiddleware` { #using-wsgimiddleware }
-/// info | Informação
+/// note | Nota
Isso requer instalar `a2wsgi`, por exemplo com `pip install a2wsgi`.
</div>
-/// info | Informação
+/// note | Nota
Há outros formatos e ferramentas para definir e instalar dependências de pacotes.
Se você tiver **múltiplos contêineres**, provavelmente cada um executando um **único processo** (por exemplo, em um cluster do **Kubernetes**), então provavelmente você gostaria de ter um **contêiner separado** fazendo o trabalho dos **passos anteriores** em um único contêiner, executando um único processo, **antes** de executar os contêineres workers replicados.
-/// info | Informação
+/// note | Nota
Se você estiver usando o Kubernetes, provavelmente será um [Init Container](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/).
# FastAPI Cloud { #fastapi-cloud }
-Você pode implantar sua aplicação FastAPI no [FastAPI Cloud](https://fastapicloud.com) com um **único comando**; entre na lista de espera, caso ainda não tenha feito isso. 🚀
-
-## Login { #login }
-
-Certifique-se de que você já tem uma conta no **FastAPI Cloud** (nós convidamos você a partir da lista de espera 😉).
-
-Depois, faça login:
-
-<div class="termy">
-
-```console
-$ fastapi login
-
-You are logged in to FastAPI Cloud 🚀
-```
-
-</div>
-
-## Implantar { #deploy }
-
-Agora, implante sua aplicação, com **um único comando**:
+Você pode implantar sua aplicação FastAPI no [FastAPI Cloud](https://fastapicloud.com) com apenas **um comando**. 🚀
<div class="termy">
</div>
+A CLI detectará automaticamente sua aplicação FastAPI e a implantará na nuvem. Se você não estiver autenticado, seu navegador será aberto para concluir o processo de autenticação.
+
É isso! Agora você pode acessar sua aplicação nesse URL. ✨
## Sobre o FastAPI Cloud { #about-fastapi-cloud }
* [Hypercorn](https://hypercorn.readthedocs.io/): um servidor ASGI compatível com HTTP/2, Trio e outros recursos.
* [Daphne](https://github.com/django/daphne): servidor ASGI construído para Django Channels.
* [Granian](https://github.com/emmett-framework/granian): um servidor HTTP Rust para aplicações Python.
-* [NGINX Unit](https://unit.nginx.org/howto/fastapi/): NGINX Unit é um runtime de aplicação web leve e versátil.
## Máquina Servidora e Programa Servidor { #server-machine-and-server-program }
Aqui mostrarei como usar o **Uvicorn** com **processos de trabalho** usando o comando `fastapi` ou o comando `uvicorn` diretamente.
-/// info | Informação
+/// note | Nota
Se você estiver usando contêineres, por exemplo com Docker ou Kubernetes, falarei mais sobre isso no próximo capítulo: [FastAPI em contêineres - Docker](docker.md).
* `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 de `app.routes`.
+* `routes`: As rotas da aplicação, obtidas de `app.routes`. O FastAPI as usa para coletar as *operações de rota* registradas, incluindo as dos routers incluídos.
-/// info | Informação
+/// tip | Detalhes Técnicos
+
+`app.routes` é uma árvore de rotas de baixo nível. Ela pode incluir rotas candidatas que o FastAPI usa internamente para routers incluídos, não apenas objetos finais `APIRoute`.
+
+Você ainda pode passar `app.routes` para `get_openapi()`. O FastAPI vai percorrer essa árvore de rotas para coletar as operações de rota efetivas.
+
+///
+
+/// note | Nota
O parâmetro `summary` está disponível no OpenAPI 3.1.0 e superior, suportado pelo FastAPI 0.99.0 e superior.
### Modelo para Dados de Resposta de Saída { #model-for-output-response-data }
-Se você interagir com a documentação e verificar a resposta, mesmo que o código não tenha adicionado nada em um dos campos `description`, a resposta JSON contém o valor padrão (`null`):
+Se você interagir com a documentação e verificar a resposta, mesmo que o código não tenha adicionado nada em um dos campos `description`, a response JSON contém o valor padrão (`null`):
<div class="screenshot">
<img src="/img/tutorial/separate-openapi-schemas/image02.png">
Agora, há alguns casos em que você pode querer ter o **mesmo esquema para entrada e saída**.
-Provavelmente, o principal caso de uso para isso é se você já tem algum código de cliente/SDK gerado automaticamente e não quer atualizar todo o código de cliente/SDK gerado ainda, você provavelmente vai querer fazer isso em algum momento, mas talvez não agora.
+Provavelmente, o principal caso de uso para isso é se você já tem algum código de cliente/SDKs gerado automaticamente e não quer atualizar todo o código de cliente/SDKs gerado ainda, você provavelmente vai querer fazer isso em algum momento, mas talvez não agora.
Nesse caso, você pode desativar esse recurso no **FastAPI**, com o parâmetro `separate_input_output_schemas=False`.
-/// info | Informação
+/// note | Nota
O suporte para `separate_input_output_schemas` foi adicionado no FastAPI `0.102.0`. 🤓
... "item_price": item.price ...
```
-...e veja como seu editor irá auto-completar os atributos e saberá os tipos:
+...e veja como seu editor irá autocompletar os atributos e saberá os tipos:
### Implemente sua aplicação (opcional) { #deploy-your-app-optional }
-Você pode opcionalmente implantar sua aplicação FastAPI na [FastAPI Cloud](https://fastapicloud.com), vá e entre na lista de espera se ainda não o fez. 🚀
-
-Se você já tem uma conta na **FastAPI Cloud** (nós convidamos você da lista de espera 😉), pode implantar sua aplicação com um único comando.
+Você pode opcionalmente implantar sua aplicação FastAPI na [FastAPI Cloud](https://fastapicloud.com) com um único comando. 🚀
<div class="termy">
</div>
+A CLI detectará automaticamente sua aplicação FastAPI e a implantará na nuvem. Se você não estiver autenticado, o navegador será aberto para concluir o processo de autenticação.
+
É isso! Agora você pode acessar sua aplicação nesse URL. ✨
#### Sobre a FastAPI Cloud { #about-fastapi-cloud }
{* ../../docs_src/bigger_applications/app_an_py310/main.py hl[10:11] title["app/main.py"] *}
-/// note | Nota
+/// note | Detalhes Técnicos
-`users.router` contém o `APIRouter` dentro do arquivo `app/routers/users.py`.
+O FastAPI mantém o `APIRouter` original e seus `APIRoute`s ativos quando o router é incluído na aplicação principal.
-E `items.router` contém o `APIRouter` dentro do arquivo `app/routers/items.py`.
+Isso significa que subclasses personalizadas de `APIRouter` e `APIRoute` ainda podem participar depois que o router é incluído.
///
Ele incluirá todas as rotas daquele router como parte dele.
-/// note | Detalhes Técnicos
-
-Na verdade, ele criará internamente uma *operação de rota* para cada *operação de rota* que foi declarada no `APIRouter`.
-
-Então, nos bastidores, ele realmente funcionará como se tudo fosse o mesmo aplicativo único.
-
-///
-
/// tip | Dica
Você não precisa se preocupar com desempenho ao incluir routers.
-Isso levará microssegundos e só acontecerá na inicialização.
+Isso foi projetado para ser leve e evitar adicionar overhead a cada request.
Então não afetará o desempenho. ⚡
Isso ocorre porque queremos incluir suas *operações de rota* no esquema OpenAPI e nas interfaces de usuário.
-Como não podemos simplesmente isolá-los e "montá-los" independentemente do resto, as *operações de rota* são "clonadas" (recriadas), não incluídas diretamente.
+O FastAPI mantém os routers e as operações de rota originais ativos e combina os prefixos, dependências, tags, responses e outros metadados do router ao tratar as requisições e gerar o OpenAPI.
///
router.include_router(other_router)
```
-Certifique-se de fazer isso antes de incluir `router` na aplicação `FastAPI`, para que as *operações de rota* de `other_router` também sejam incluídas.
+Você pode fazer isso antes ou depois de incluir o `router` na aplicação `FastAPI`. O FastAPI ainda incluirá as *operações de rota* de `other_router` no roteamento e no OpenAPI.
+
+O mesmo vale para *operações de rota* adicionadas depois aos routers. Elas também ficarão visíveis por meio da inclusão anterior.
+
+/// warning | Detalhes Técnicos
+
+Evite mutar diretamente `router.routes` após incluir um router. O FastAPI trata a inclusão de routers como algo ativo, então o router original e suas rotas permanecem parte do roteamento e da geração do OpenAPI.
+
+Use APIs documentadas como os decoradores de operações de rota e `.include_router()` para adicionar rotas e routers.
+
+Trate `router.routes` como uma árvore de rotas de nível mais baixo que pode conter definições de rotas e routers incluídos, e evite depender dela como uma lista plana de operações de rota finais.
+
+///
{* ../../docs_src/body_multiple_params/tutorial004_an_py310.py hl[28] *}
-/// info | Informação
+/// note | Nota
`Body` também possui todas as validações adicionais e metadados de parâmetros como em `Query`,`Path` e outras que você verá depois.
Mas se você quiser que ele espere por um JSON com uma chave `item` e dentro dele os conteúdos do modelo, como ocorre ao declarar vários parâmetros de corpo, você pode usar o parâmetro especial de `Body` chamado `embed`:
```Python
-item: Item = Body(embed=True)
+item: Annotated[Item, Body(embed=True)]
```
como em:
}
```
-/// info | Informação
+/// note | Nota
Observe como a chave `images` agora tem uma lista de objetos de imagem.
{* ../../docs_src/body_nested_models/tutorial007_py310.py hl[7,12,18,21,25] *}
-/// info | Informação
+/// note | Nota
Observe como `Offer` tem uma lista de `Item`s, que por sua vez têm uma lista opcional de `Image`s
Para declarar um corpo da **requisição**, você utiliza os modelos do [Pydantic](https://docs.pydantic.dev/) com todos os seus poderes e benefícios.
-/// info | Informação
+/// note | Nota
Para enviar dados, você deveria usar um dos: `POST` (o mais comum), `PUT`, `DELETE` ou `PATCH`.
<img src="/img/tutorial/cookie-param-models/image01.png">
</div>
-/// info | Informação
+/// note | Nota
Tenha em mente que, como os **navegadores lidam com cookies** de maneira especial e por baixo dos panos, eles **não** permitem facilmente que o **JavaScript** lidem com eles.
///
-/// info | Informação
+/// note | Nota
Para declarar cookies, você precisa usar `Cookie`, pois caso contrário, os parâmetros seriam interpretados como parâmetros de consulta.
///
-/// info | Informação
+/// note | Nota
Tenha em mente que, como os **navegadores lidam com cookies** de maneiras especiais e nos bastidores, eles **não** permitem facilmente que o **JavaScript** os acesse.
///
-/// info | Informação
+/// note | Nota
Neste exemplo utilizamos cabeçalhos personalizados inventados `X-Key` e `X-Token`.
Neste caso, o cliente irá ver uma resposta *HTTP 500 Internal Server Error* como deveria acontecer, já que não estamos levantando nenhuma `HTTPException` ou coisa parecida, mas o servidor **não terá nenhum log** ou qualquer outra indicação de qual foi o erro. 😱
-### Sempre levante (`raise`) em Dependências com `yield` e `except` { #always-raise-in-dependencies-with-yield-and-except }
+### Sempre `raise` em Dependências com `yield` e `except` { #always-raise-in-dependencies-with-yield-and-except }
Se você capturar uma exceção em uma dependência com `yield`, a menos que você esteja levantando outra `HTTPException` ou coisa parecida, **você deve relançar a exceção original**.
end
```
-/// info | Informação
+/// note | Nota
Apenas **uma resposta** será enviada para o cliente. Ela pode ser uma das respostas de erro, ou então a resposta da *operação de rota*.
E então retorna um `dict` contendo esses valores.
-/// info | Informação
+/// note | Nota
FastAPI passou a suportar a notação `Annotated` (e começou a recomendá-la) na versão 0.95.0.
Assim, você escreve um código compartilhado apenas uma vez e o **FastAPI** se encarrega de chamá-lo em suas *operações de rota*.
-/// check | Verifique
+/// tip | Dica
Perceba que você não precisa criar uma classe especial e enviar a dependência para algum outro lugar em que o **FastAPI** a "registre" ou realize qualquer operação similar.
///
-As dependências continuarão funcionando como esperado, e a **melhor parte** é que a **informação sobre o tipo é preservada**, o que signfica que seu editor de texto ainda irá incluir **preenchimento automático**, **visualização de erros**, etc. O mesmo vale para ferramentas como `mypy`.
+As dependências continuarão funcionando como esperado, e a **melhor parte** é que a **informação sobre o tipo é preservada**, o que significa que seu editor de texto ainda irá incluir **preenchimento automático**, **erros em linha**, etc. O mesmo vale para ferramentas como `mypy`.
Isso é especialmente útil para uma **base de código grande** onde **as mesmas dependências** são utilizadas repetidamente em **muitas *operações de rota***.
/// note | Nota
-Caso você não conheça, veja em [Async: *"Com Pressa?"*](../../async.md#in-a-hurry) a sessão acerca de `async` e `await` na documentação.
+Caso você não conheça, veja em [Async: *"Com Pressa?"*](../../async.md#in-a-hurry) a seção acerca de `async` e `await` na documentação.
///
{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[23] *}
-/// info | Informação
+/// note | Nota
Perceba que nós estamos declarando apenas uma dependência na *função de operação de rota*, em `query_or_cookie_extractor`.
from backend.main import app
```
-### `fastapi dev` com path { #fastapi-dev-with-path }
+### `fastapi dev` com path ou com a opção de CLI `--entrypoint` { #fastapi-dev-with-path-or-with-entrypoint-cli-option }
Você também pode passar o path do arquivo para o comando `fastapi dev`, e ele vai deduzir o objeto de aplicação FastAPI a ser usado:
$ fastapi dev main.py
```
-Mas você teria que lembrar de passar o path correto toda vez que chamar o comando `fastapi`.
-
-Além disso, outras ferramentas podem não conseguir encontrá-la, por exemplo, a [Extensão do VS Code](../editor-support.md) ou a [FastAPI Cloud](https://fastapicloud.com), então é recomendado usar o `entrypoint` no `pyproject.toml`.
-
-### Faça o deploy da sua aplicação (opcional) { #deploy-your-app-optional }
-
-Você pode, opcionalmente, fazer o deploy da sua aplicação FastAPI na [FastAPI Cloud](https://fastapicloud.com); acesse e entre na lista de espera, se ainda não entrou. 🚀
-
-Se você já tem uma conta na **FastAPI Cloud** (nós convidamos você da lista de espera 😉), pode fazer o deploy da sua aplicação com um único comando.
-
-Antes do deploy, certifique-se de que está autenticado:
-
-<div class="termy">
+Ou você também pode passar a opção `--entrypoint` para o comando `fastapi dev`:
```console
-$ fastapi login
-
-You are logged in to FastAPI Cloud 🚀
+$ fastapi dev --entrypoint main:app
```
-</div>
+Mas você teria que lembrar de passar o path\entrypoint correto toda vez que chamar o comando `fastapi`.
+
+Além disso, outras ferramentas podem não conseguir encontrá-la, por exemplo, a [Extensão do VS Code](../editor-support.md) ou a [FastAPI Cloud](https://fastapicloud.com), então é recomendado usar o `entrypoint` no `pyproject.toml`.
-Em seguida, faça o deploy da sua aplicação:
+### Faça o deploy da sua aplicação (opcional) { #deploy-your-app-optional }
+
+Você pode, opcionalmente, fazer o deploy da sua aplicação FastAPI na [FastAPI Cloud](https://fastapicloud.com) com um único comando. 🚀
<div class="termy">
</div>
+A CLI detectará automaticamente sua aplicação FastAPI e a fará o deploy na nuvem. Se você não estiver autenticado, o seu navegador será aberto para concluir o processo de autenticação.
+
É isso! Agora você pode acessar sua aplicação nessa URL. ✨
## Recapitulando, passo a passo { #recap-step-by-step }
/items/foo
```
-/// info | Informação
+/// note | Nota
Um "path" também é comumente chamado de "endpoint" ou de "rota".
* o path `/`
* usando uma <dfn title="um método HTTP GET"><code>get</code> operação</dfn>
-/// info | Informações sobre `@decorator`
+/// note | Informações sobre `@decorator`
Essa sintaxe `@alguma_coisa` em Python é chamada de "decorador".
{* ../../docs_src/metadata/tutorial004_py310.py hl[21,26] *}
-/// info | Informação
+/// note | Nota
Leia mais sobre tags em [Configuração de operação de rota](path-operation-configuration.md#tags).
{* ../../docs_src/path_operation_configuration/tutorial005_py310.py hl[18] *}
-/// info | Informação
+/// note | Nota
-Note que `response_description` se refere especificamente à resposta, a `description` se refere à *operação de rota* em geral.
+Observe que `response_description` se refere especificamente à resposta, a `description` se refere à *operação de rota* em geral.
///
-/// check | Verifique
+/// tip | Dica
OpenAPI especifica que cada *operação de rota* requer uma descrição de resposta.
{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[1,3] *}
-/// info | Informação
+/// note | Nota
O FastAPI adicionou suporte a `Annotated` (e passou a recomendá-lo) na versão 0.95.0.
* `lt`: menor que (`l`ess `t`han)
* `le`: menor que ou igual (`l`ess than or `e`qual)
-/// info | Informação
+/// note | Nota
`Query`, `Path` e outras classes que você verá depois são subclasses de uma classe comum `Param`.
Neste caso, `item_id` é declarado como um `int`.
-/// check | Verifique
+/// tip | Dica
Isso fornecerá suporte do editor dentro da sua função, com verificações de erros, preenchimento automático, etc.
///
{"item_id":3}
```
-/// check | Verifique
+/// tip | Dica
Perceba que o valor que sua função recebeu (e retornou) é `3`, como um `int` do Python, não uma string `"3"`.
Então, com essa declaração de tipo, o **FastAPI** fornece <dfn title="convertendo a string que vem de um request HTTP em dados Python">"parsing"</dfn> automático do request.
O mesmo erro apareceria se você fornecesse um `float` em vez de um `int`, como em: [http://127.0.0.1:8000/items/4.2](http://127.0.0.1:8000/items/4.2)
-/// check | Verifique
+/// tip | Dica
Então, com a mesma declaração de tipo do Python, o **FastAPI** fornece validação de dados.
Observe que o erro também declara claramente exatamente o ponto onde a validação não passou.
<img src="/img/tutorial/path-params/image01.png">
-/// check | Verifique
+/// tip | Dica
Novamente, apenas com a mesma declaração de tipo do Python, o **FastAPI** fornece documentação automática e interativa (integrando o Swagger UI).
Observe que o parâmetro de path está declarado como um inteiro.
{* ../../docs_src/query_params_str_validations/tutorial002_an_py310.py hl[1,3] *}
-/// info | Informação
+/// note | Nota
O FastAPI adicionou suporte a `Annotated` (e passou a recomendá-lo) na versão 0.95.0.
Tenha em mente que, neste caso, o FastAPI não verificará o conteúdo da lista.
-Por exemplo, `list[int]` verificaria (and documentaria) que os conteúdos da lista são inteiros. Mas `list` sozinho não.
+Por exemplo, `list[int]` verificaria (e documentaria) que os conteúdos da lista são inteiros. Mas `list` sozinho não.
///
{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py hl[5,16:19,24] *}
-/// info | Informação
+/// note | Nota
Isso está disponível com a versão 2 do Pydantic ou superior. 😎
Com `data.items()` obtemos um <dfn title="Algo que podemos iterar com um laço for, como uma list, set, etc.">objeto iterável</dfn> com tuplas contendo a chave e o valor de cada item do dicionário.
-Convertimos esse objeto iterável em uma `list` adequada com `list(data.items())`.
+Convertemos esse objeto iterável em uma `list` adequada com `list(data.items())`.
Em seguida, com `random.choice()` podemos obter um valor aleatório da lista, então obtemos uma tupla com `(id, name)`. Será algo como `("imdb-tt0371724", "The Hitchhiker's Guide to the Galaxy")`.
Nesse caso, o parâmetro da função `q` será opcional, e `None` será o padrão.
-/// check | Verifique
+/// tip | Dica
Você também pode notar que o **FastAPI** é esperto o suficiente para perceber que o parâmetro da rota `item_id` é um parâmetro da rota, e `q` não é, portanto, `q` é o parâmetro de consulta.
Você pode definir arquivos para serem enviados pelo cliente usando `File`.
-/// info | Informação
+/// note | Nota
Para receber arquivos enviados, primeiro instale [`python-multipart`](https://github.com/Kludex/python-multipart).
{* ../../docs_src/request_files/tutorial001_an_py310.py hl[9] *}
-/// info | Informação
+/// note | Nota
`File` é uma classe que herda diretamente de `Form`.
Você pode utilizar **Modelos Pydantic** para declarar **campos de formulários** no FastAPI.
-/// info | Informação
+/// note | Nota
Para utilizar formulários, instale primeiramente o [`python-multipart`](https://github.com/Kludex/python-multipart).
O **FastAPI** irá **extrair** as informações para **cada campo** dos **dados do formulário** na requisição e dar para você o modelo Pydantic que você definiu.
-## Confira os Documentos { #check-the-docs }
+## Confira a Documentação { #check-the-docs }
Você pode verificar na UI de documentação em `/docs`:
Você pode definir arquivos e campos de formulário ao mesmo tempo usando `File` e `Form`.
-/// info | Informação
+/// note | Nota
Para receber arquivos carregados e/ou dados de formulário, primeiro instale [`python-multipart`](https://github.com/Kludex/python-multipart).
Quando você precisar receber campos de formulário em vez de JSON, você pode usar `Form`.
-/// info | Informação
+/// note | Nota
Para usar formulários, primeiro instale [`python-multipart`](https://github.com/Kludex/python-multipart).
Com `Form` você pode declarar as mesmas configurações que com `Body` (e `Query`, `Path`, `Cookie`), incluindo validação, exemplos, um alias (por exemplo, `user-name` em vez de `username`), etc.
-/// info | Informação
+/// note | Nota
`Form` é uma classe que herda diretamente de `Body`.
{* ../../docs_src/response_model/tutorial002_py310.py hl[7,9] *}
-/// info | Informação
+/// note | Nota
Para usar `EmailStr`, primeiro instale [`email-validator`](https://github.com/JoshData/python-email-validator).
}
```
-/// info | Informação
+/// note | Nota
Você também pode usar:
O parâmetro `status_code` recebe um número com o código de status HTTP.
-/// info | Informação
+/// note | Nota
`status_code` também pode receber um `IntEnum`, como [`http.HTTPStatus`](https://docs.python.org/3/library/http.html#http.HTTPStatus) do Python.
///
-/// info | Informação
+/// note | Nota
O OpenAPI 3.1.0 (usado desde o FastAPI 0.99.0) adicionou suporte a `examples`, que faz parte do padrão **JSON Schema**.
* `File()`
* `Form()`
-/// info | Informação
+/// note | Nota
Esse parâmetro antigo `examples` específico do OpenAPI agora é `openapi_examples` desde o FastAPI `0.103.0`.
Esse novo campo `examples` no JSON Schema é **apenas uma `list`** de exemplos, não um dict com metadados extras como nos outros lugares do OpenAPI (descritos acima).
-/// info | Informação
+/// note | Nota
Mesmo após o lançamento do OpenAPI 3.1.0 com essa nova integração mais simples com o JSON Schema, por um tempo o Swagger UI, a ferramenta que fornece a documentação automática, não suportava OpenAPI 3.1.0 (passou a suportar desde a versão 5.0.0 🎉).
## Execute-o { #run-it }
-/// info | Informação
+/// note | Nota
O pacote [`python-multipart`](https://github.com/Kludex/python-multipart) é instalado automaticamente com o **FastAPI** quando você executa o comando `pip install "fastapi[standard]"`.
<img src="/img/tutorial/security/image01.png">
-/// check | Botão Autorizar!
+/// tip | Botão Autorizar!
Você já tem um novo botão 'Authorize'.
Neste exemplo, vamos usar **OAuth2**, com o fluxo **Password**, usando um token **Bearer**. Fazemos isso usando a classe `OAuth2PasswordBearer`.
-/// info | Informação
+/// note | Nota
Um token "bearer" não é a única opção.
Em breve também criaremos a operação de rota real.
-/// info | Informação
+/// note | Nota
Se você é um "Pythonista" muito rigoroso, pode não gostar do estilo do nome do parâmetro `tokenUrl` em vez de `token_url`.
O **FastAPI** saberá que pode usar essa dependência para definir um "esquema de segurança" no esquema OpenAPI (e na documentação automática da API).
-/// info | Detalhes Técnicos
+/// note | Detalhes Técnicos
O **FastAPI** saberá que pode usar a classe `OAuth2PasswordBearer` (declarada em uma dependência) para definir o esquema de segurança no OpenAPI porque ela herda de `fastapi.security.oauth2.OAuth2`, que por sua vez herda de `fastapi.security.base.SecurityBase`.
## Criar uma dependência `get_current_user` { #create-a-get-current-user-dependency }
-Vamos criar uma dependência chamada `get_current_user`.
+Vamos criar uma dependência `get_current_user`.
Lembra que as dependências podem ter subdependências?
///
-/// check | Verifique
+/// tip | Dica
A forma como esse sistema de dependências foi projetado nos permite ter diferentes dependências (diferentes "dependables") que retornam um modelo `User`.
</div>
-/// info | Informação
+/// note | Nota
-Se você pretente utilizar algoritmos de assinatura digital como o RSA ou o ECDSA, você deve instalar a dependência da biblioteca de criptografia `pyjwt[crypto]`.
+Se você pretende utilizar algoritmos de assinatura digital como o RSA ou o ECDSA, você deve instalar a dependência da biblioteca de criptografia `pyjwt[crypto]`.
Você pode ler mais sobre isso na [documentação de instalação do PyJWT](https://pyjwt.readthedocs.io/en/latest/installation.html).
Username: `johndoe`
Password: `secret`
-/// check | Verifique
+/// tip | Dica
Observe que em nenhuma parte do código está a senha em texto puro "`secret`", nós temos apenas o hash.
## Obtenha o `username` e a `password` { #get-the-username-and-password }
-É utilizado o utils de segurança da **FastAPI** para obter o `username` e a `password`.
+Vamos usar os utilitários de segurança da **FastAPI** para obter o `username` e a `password`.
OAuth2 especifica que ao usar o "password flow" (fluxo de senha), que estamos usando, o cliente/usuário deve enviar os campos `username` e `password` como dados do formulário.
* `instagram_basic` é usado pelo Facebook e Instagram.
* `https://www.googleapis.com/auth/drive` é usado pelo Google.
-/// info | Informação
+/// note | Nota
No OAuth2, um "scope" é apenas uma string que declara uma permissão específica necessária.
* Um `client_id` opcional (não precisamos dele em nosso exemplo).
* Um `client_secret` opcional (não precisamos dele em nosso exemplo).
-/// info | Informação
+/// note | Nota
O `OAuth2PasswordRequestForm` não é uma classe especial para **FastAPI** como é `OAuth2PasswordBearer`.
)
```
-
-/// info | Informação
+/// note | Nota
Para uma explicação mais completa de `**user_dict`, verifique [a documentação para **Extra Models**](../extra-models.md#about-user-in-dict).
/// tip | Dica
-Pela especificação, você deve retornar um JSON com um `access_token` e um `token_type`, o mesmo que neste exemplo.
+Pela especificação, você deveria retornar um JSON com um `access_token` e um `token_type`, o mesmo que neste exemplo.
Isso é algo que você mesmo deve fazer em seu código e certifique-se de usar essas chaves JSON.
{* ../../docs_src/security/tutorial003_an_py310.py hl[58:66,69:74,94] *}
-/// info | Informação
+/// note | Nota
O cabeçalho adicional `WWW-Authenticate` com valor `Bearer` que estamos retornando aqui também faz parte da especificação.
## Veja em ação { #see-it-in-action }
-Abra o docs interativo: [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs).
+Abra a documentação interativa: [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs).
### Autentique-se { #authenticate }
Isso é semelhante a [Stream de JSON Lines](stream-json-lines.md), mas usa o formato `text/event-stream`, que é suportado nativamente pelos navegadores com a [`EventSource` API](https://developer.mozilla.org/en-US/docs/Web/API/EventSource).
-/// info | Informação
+/// note | Nota
Adicionado no FastAPI 0.135.0.
Você pode ter uma sequência de dados que deseja enviar em um "**Stream**"; é possível fazer isso com **JSON Lines**.
-/// info | Informação
+/// note | Nota
Adicionado no FastAPI 0.134.0.
É muito semelhante a um array JSON (equivalente a uma list do Python), mas em vez de estar envolto em `[]` e ter `,` entre os itens, há **um objeto JSON por linha**, separados por um caractere de nova linha.
-/// info | Informação
+/// note | Nota
O ponto importante é que sua aplicação poderá produzir cada linha em sequência, enquanto o cliente consome as anteriores.
## Usando `TestClient` { #using-testclient }
-/// info | Informação
+/// note | Nota
Para usar o `TestClient`, primeiro instale [`httpx`](https://www.python-httpx.org).
Para mais informações sobre como passar dados para o backend (usando `httpx` ou `TestClient`), consulte a [documentação do HTTPX](https://www.python-httpx.org).
-/// info | Informação
+/// note | Nota
Observe que o `TestClient` recebe dados que podem ser convertidos para JSON, não para modelos Pydantic.
projects / thirdparty / fastapi / fastapi.git / commitdiff
