@ -199,7 +199,7 @@ Você pode declarar um `response_model`, utilizando o código de status padrão
O **FastAPI** manterá as informações adicionais do `responses`, e combinará com o esquema JSON do seu modelo.
O **FastAPI** manterá as informações adicionais do `responses`, e combinará com o esquema JSON do seu modelo.
Por exemplo, você pode declarar um retorno com o código de status `404` que utiliza um modelo do Pydantic que possui um `description` customizado.
Por exemplo, você pode declarar um retorno com o código de status `404` que utiliza um modelo do Pydantic e tem uma `description` customizada.
E um retorno com o código de status `200` que utiliza o seu `response_model`, porém inclui um `example` customizado:
E um retorno com o código de status `200` que utiliza o seu `response_model`, porém inclui um `example` customizado:
@ -243,5 +243,5 @@ Por exemplo:
Para verificar exatamente o que você pode incluir nos retornos, você pode conferir estas seções na especificação do OpenAPI:
Para verificar exatamente o que você pode incluir nos retornos, você pode conferir estas seções na especificação do OpenAPI:
* <ahref="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object"class="external-link"target="_blank">Objeto de Retornos do OpenAPI</a>, inclui o `Response Object`.
* [Objeto de Retornos do OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object), inclui o `Response Object`.
* <ahref="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object"class="external-link"target="_blank">Objeto de Retorno do OpenAPI</a>, você pode incluir qualquer coisa dele diretamente em cada retorno dentro do seu parâmetro `responses`. Incluindo `description`, `headers`, `content` (dentro dele que você declara diferentes media types e esquemas JSON), e `links`.
* [Objeto de Retorno do OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object), você pode incluir qualquer coisa dele diretamente em cada retorno dentro do seu parâmetro `responses`. Incluindo `description`, `headers`, `content` (dentro dele que você declara diferentes media types e esquemas JSON), e `links`.
@ -38,4 +38,4 @@ O **FastAPI** disponibiliza o `starlette.responses` como `fastapi.responses` ape
Se você retorna códigos de status adicionais e retornos diretamente, eles não serão incluídos no esquema do OpenAPI (a documentação da API), porque o FastAPI não tem como saber de antemão o que será retornado.
Se você retorna códigos de status adicionais e retornos diretamente, eles não serão incluídos no esquema do OpenAPI (a documentação da API), porque o FastAPI não tem como saber de antemão o que será retornado.
Mas você pode documentar isso no seu código, utilizando: [Retornos Adicionais](additional-responses.md){.internal-link target=_blank}.
Mas você pode documentar isso no seu código, utilizando: [Retornos Adicionais](additional-responses.md).
Se você quiser saber mais sobre HTTPS, confira o tutorial [Sobre HTTPS](../deployment/https.md){.internal-link target=_blank}.
Se você quiser saber mais sobre HTTPS, confira o tutorial [Sobre HTTPS](../deployment/https.md).
///
///
@ -228,7 +228,7 @@ Passar o `root_path` para `FastAPI` seria o equivalente a passar a opção de li
Tenha em mente que o servidor (Uvicorn) não usará esse `root_path` para nada além de passá-lo para a aplicação.
Tenha em mente que o servidor (Uvicorn) não usará esse `root_path` para nada além de passá-lo para a aplicação.
Mas se você acessar com seu navegador <ahref="http://127.0.0.1:8000/app"class="external-link"target="_blank">http://127.0.0.1:8000/app</a> você verá a resposta normal:
Mas se você acessar com seu navegador [http://127.0.0.1:8000/app](http://127.0.0.1:8000/app) você verá a resposta normal:
```JSON
```JSON
{
{
@ -251,9 +251,9 @@ Em um caso como esse (sem um prefixo de path removido), o proxy escutaria em alg
## Testando localmente com Traefik { #testing-locally-with-traefik }
## Testando localmente com Traefik { #testing-locally-with-traefik }
Você pode facilmente executar o experimento localmente com um prefixo de path removido usando <ahref="https://docs.traefik.io/"class="external-link"target="_blank">Traefik</a>.
Você pode facilmente executar o experimento localmente com um prefixo de path removido usando [Traefik](https://docs.traefik.io/).
<ahref="https://github.com/containous/traefik/releases"class="external-link"target="_blank">Faça o download do Traefik</a>, ele é um único binário, você pode extrair o arquivo compactado e executá-lo diretamente do terminal.
[Faça o download do Traefik](https://github.com/containous/traefik/releases), ele é um único binário, você pode extrair o arquivo compactado e executá-lo diretamente do terminal.
### Verifique as respostas { #check-the-responses }
### Verifique as respostas { #check-the-responses }
Agora, se você for ao URL com a porta para o Uvicorn: <ahref="http://127.0.0.1:8000/app"class="external-link"target="_blank">http://127.0.0.1:8000/app</a>, você verá a resposta normal:
Agora, se você for ao URL com a porta para o Uvicorn: [http://127.0.0.1:8000/app](http://127.0.0.1:8000/app), você verá a resposta normal:
```JSON
```JSON
{
{
@ -345,7 +345,7 @@ Perceba que, mesmo acessando em `http://127.0.0.1:8000/app`, ele mostra o `root_
///
///
E agora abra o URL com a porta para o Traefik, incluindo o prefixo de path: <ahref="http://127.0.0.1:9999/api/v1/app"class="external-link"target="_blank">http://127.0.0.1:9999/api/v1/app</a>.
E agora abra o URL com a porta para o Traefik, incluindo o prefixo de path: [http://127.0.0.1:9999/api/v1/app](http://127.0.0.1:9999/api/v1/app).
Obtemos a mesma resposta:
Obtemos a mesma resposta:
@ -370,13 +370,13 @@ Mas aqui está a parte divertida. ✨
A maneira "oficial" de acessar a aplicação seria através do proxy com o prefixo de path que definimos. Então, como esperaríamos, se você tentar a interface de documentação servida diretamente pelo Uvicorn, sem o prefixo de path no URL, ela não funcionará, porque espera ser acessada através do proxy.
A maneira "oficial" de acessar a aplicação seria através do proxy com o prefixo de path que definimos. Então, como esperaríamos, se você tentar a interface de documentação servida diretamente pelo Uvicorn, sem o prefixo de path no URL, ela não funcionará, porque espera ser acessada através do proxy.
Você pode verificar em <ahref="http://127.0.0.1:8000/docs"class="external-link"target="_blank">http://127.0.0.1:8000/docs</a>:
Você pode verificar em [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs):
@ -433,7 +433,7 @@ Perceba o servidor gerado automaticamente com um valor `url` de `/api/v1`, retir
///
///
Na interface de documentação em <ahref="http://127.0.0.1:9999/api/v1/docs"class="external-link"target="_blank">http://127.0.0.1:9999/api/v1/docs</a> parecerá:
Na interface de documentação em [http://127.0.0.1:9999/api/v1/docs](http://127.0.0.1:9999/api/v1/docs) parecerá:
@ -461,6 +461,6 @@ e então ele não será incluído no OpenAPI schema.
## Montando uma sub-aplicação { #mounting-a-sub-application }
## Montando uma sub-aplicação { #mounting-a-sub-application }
Se você precisar montar uma sub-aplicação (como descrito em [Sub-aplicações - Montagens](sub-applications.md){.internal-link target=_blank}) enquanto também usa um proxy com `root_path`, você pode fazer isso normalmente, como esperaria.
Se você precisar montar uma sub-aplicação (como descrito em [Sub-aplicações - Montagens](sub-applications.md)) enquanto também usa um proxy com `root_path`, você pode fazer isso normalmente, como esperaria.
O FastAPI usará internamente o `root_path` de forma inteligente, então tudo funcionará. ✨
O FastAPI usará internamente o `root_path` de forma inteligente, então tudo funcionará. ✨
# Resposta Personalizada - HTML, Stream, File e outras { #custom-response-html-stream-file-others }
# Resposta Personalizada - HTML, Stream, File e outras { #custom-response-html-stream-file-others }
Por padrão, o **FastAPI**irá retornar respostas utilizando `JSONResponse`.
Por padrão, o **FastAPI** retornará respostas JSON.
Mas você pode sobrescrever esse comportamento utilizando`Response` diretamente, como visto em [Retornando uma Resposta Diretamente](response-directly.md){.internal-link target=_blank}.
Você pode sobrescrever isso retornando uma`Response` diretamente, como visto em [Retornando uma Resposta Diretamente](response-directly.md).
Mas se você retornar uma `Response` diretamente (ou qualquer subclasse, como `JSONResponse`), os dados não serão convertidos automaticamente (mesmo que você declare um `response_model`), e a documentação não será gerada automaticamente (por exemplo, incluindo o "media type", no cabeçalho HTTP `Content-Type` como parte do esquema OpenAPI gerado).
Mas se você retornar uma `Response` diretamente (ou qualquer subclasse, como `JSONResponse`), os dados não serão convertidos automaticamente (mesmo que você declare um `response_model`), e a documentação não será gerada automaticamente (por exemplo, incluindo o "media type" específico, no cabeçalho HTTP `Content-Type` como parte do OpenAPI gerado).
Mas você também pode declarar a `Response` que você deseja utilizar (e.g. qualquer subclasse de `Response`), em um *decorador de operação de rota* utilizando o parâmetro `response_class`.
Mas você também pode declarar a `Response` que deseja utilizar (e.g. qualquer subclasse de `Response`), no *decorador de operação de rota* usando o parâmetro `response_class`.
Os conteúdos que você retorna em sua *função de operação de rota* serão colocados dentro dessa `Response`.
O conteúdo que você retorna da sua *função de operação de rota* será colocado dentro dessa `Response`.
E se a `Response` tiver um media type JSON (`application/json`), como é o caso com `JSONResponse` e `UJSONResponse`, os dados que você retornar serão automaticamente convertidos (e filtrados) com qualquer `response_model` do Pydantic que for declarado no decorador de operação de rota.
/// note | Nota
/// note | Nota
Se você utilizar uma classe de Resposta sem media type, o FastAPI esperará que sua resposta não tenha conteúdo, então ele não irá documentar o formato da resposta na documentação OpenAPI gerada.
Se você utilizar uma classe de resposta sem media type, o FastAPI esperará que sua resposta não tenha conteúdo, então ele não irá documentar o formato da resposta na documentação OpenAPI gerada.
Por exemplo, se você precisa bastante de performance, você pode instalar e utilizar o <ahref="https://github.com/ijl/orjson"class="external-link"target="_blank">`orjson`</a> e definir a resposta para ser uma `ORJSONResponse`.
Importe a classe, ou subclasse, de `Response` que você deseja utilizar e declare ela no *decorador de operação de rota*.
Para respostas grandes, retornar uma `Response` diretamente é muito mais rápido que retornar um dicionário.
Isso ocorre por que, por padrão, o FastAPI irá verificar cada item dentro do dicionário e garantir que ele seja serializável para JSON, utilizando o mesmo[Codificador Compatível com JSON](../tutorial/encoder.md){.internal-link target=_blank} explicado no tutorial. Isso permite que você retorne **objetos abstratos**, como modelos do banco de dados, por exemplo.
Mas se você tem certeza que o conteúdo que você está retornando é **serializável com JSON**, você pode passá-lo diretamente para a classe de resposta e evitar o trabalho extra que o FastAPI teria ao passar o conteúdo pelo `jsonable_encoder` antes de passar para a classe de resposta.
Se você declarar um [Modelo de Resposta](../tutorial/response-model.md), o FastAPI irá usá-lo para serializar os dados para JSON, usando Pydantic.
O parâmetro `response_class` também será usado para definir o "media type" da resposta.
Neste caso, o cabeçalho HTTP `Content-Type` irá ser definido como `application/json`.
Se você não declarar um modelo de resposta, o FastAPI usará o `jsonable_encoder` explicado em [Codificador Compatível com JSON](../tutorial/encoder.md) e o colocará em uma `JSONResponse`.
E será documentado como tal no OpenAPI.
Se você declarar uma `response_class` com um media type JSON (`application/json`), como no caso de `JSONResponse`, os dados que você retorna serão automaticamente convertidos (e filtrados) com qualquer `response_model` do Pydantic que você declarou no *decorador de operação de rota*. Mas os dados não serão serializados para bytes JSON com Pydantic; em vez disso, serão convertidos com o `jsonable_encoder` e então passados para a classe `JSONResponse`, que fará a serialização para bytes usando a biblioteca padrão de JSON do Python.
///
### Performance com JSON { #json-performance }
/// tip | Dica
Resumindo, se você quer o máximo de performance, use um [Modelo de Resposta](../tutorial/response-model.md) e não declare uma `response_class` no *decorador de operação de rota*.
A `ORJSONResponse` está disponível apenas no FastAPI, e não no Starlette.
@ -69,7 +53,7 @@ E será documentado como tal no OpenAPI.
### Retornando uma `Response` { #return-a-response }
### Retornando uma `Response` { #return-a-response }
Como visto em [Retornando uma Resposta Diretamente](response-directly.md){.internal-link target=_blank}, você também pode sobrescrever a resposta diretamente na sua *operação de rota*, ao retornar ela.
Como visto em [Retornando uma Resposta Diretamente](response-directly.md), você também pode sobrescrever a resposta diretamente na sua *operação de rota*, ao retornar ela.
O mesmo exemplo de antes, retornando uma `HTMLResponse`, poderia parecer com:
O mesmo exemplo de antes, retornando uma `HTMLResponse`, poderia parecer com:
@ -103,13 +87,13 @@ Neste exemplo, a função `generate_html_response()` já cria e retorna uma `Res
Ao retornar o resultado chamando `generate_html_response()`, você já está retornando uma `Response` que irá sobrescrever o comportamento padrão do **FastAPI**.
Ao retornar o resultado chamando `generate_html_response()`, você já está retornando uma `Response` que irá sobrescrever o comportamento padrão do **FastAPI**.
Mas se você passasse uma`HTMLResponse` em `response_class` também, o **FastAPI** saberia como documentar isso no OpenAPI e na documentação interativa como um HTML com `text/html`:
Mas como você passou`HTMLResponse` em `response_class` também, o **FastAPI** saberá como documentar isso no OpenAPI e na documentação interativa como um HTML com `text/html`:
Aqui estão algumas dos tipos de resposta disponíveis.
Aqui estão algumas das respostas disponíveis.
Lembre-se que você pode utilizar `Response` para retornar qualquer outra coisa, ou até mesmo criar uma subclasse personalizada.
Lembre-se que você pode utilizar `Response` para retornar qualquer outra coisa, ou até mesmo criar uma subclasse personalizada.
@ -129,9 +113,9 @@ Você pode retorná-la diretamente.
Ela aceita os seguintes parâmetros:
Ela aceita os seguintes parâmetros:
* `content` - Uma sequência de caracteres (`str`) ou `bytes`.
* `content` - Uma `str` ou `bytes`.
* `status_code` - Um código de status HTTP do tipo `int`.
* `status_code` - Um código de status HTTP do tipo `int`.
* `headers` - Um dicionário `dict` de strings.
* `headers` - Um `dict` de strings.
* `media_type` - Uma `str` informando o media type. E.g. `"text/html"`.
* `media_type` - Uma `str` informando o media type. E.g. `"text/html"`.
O FastAPI (Starlette, na verdade) irá incluir o cabeçalho Content-Length automaticamente. Ele também irá incluir o cabeçalho Content-Type, baseado no `media_type` e acrescentando uma codificação para tipos textuais.
O FastAPI (Starlette, na verdade) irá incluir o cabeçalho Content-Length automaticamente. Ele também irá incluir o cabeçalho Content-Type, baseado no `media_type` e acrescentando uma codificação para tipos textuais.
@ -154,37 +138,11 @@ Pega alguns dados e retorna uma resposta com codificação `application/json`.
É a resposta padrão utilizada no **FastAPI**, como você leu acima.
É a resposta padrão utilizada no **FastAPI**, como você leu acima.
### `ORJSONResponse` { #orjsonresponse }
/// note | Detalhes Técnicos
Uma alternativa mais rápida de resposta JSON utilizando o <ahref="https://github.com/ijl/orjson"class="external-link"target="_blank">`orjson`</a>, como você leu acima.
/// info | Informação
Essa resposta requer a instalação do pacote `orjson`, com o comando `pip install orjson`, por exemplo.
///
### `UJSONResponse` { #ujsonresponse }
Uma alternativa de resposta JSON utilizando a biblioteca <ahref="https://github.com/ultrajson/ultrajson"class="external-link"target="_blank">`ujson`</a>.
/// info | Informação
Essa resposta requer a instalação do pacote `ujson`, com o comando `pip install ujson`, por exemplo.
///
/// warning | Atenção
`ujson` é menos cauteloso que a implementação nativa do Python na forma que os casos especiais são tratados
Mas se você declarar um modelo de resposta ou tipo de retorno, isso será usado diretamente para serializar os dados para JSON, e uma resposta com o media type correto para JSON será retornada diretamente, sem usar a classe `JSONResponse`.
É possível que `ORJSONResponse` seja uma alternativa mais rápida.
Esta é a forma ideal para obter a melhor performance.
///
///
@ -202,9 +160,9 @@ Ou você pode utilizá-la no parâmetro `response_class`:
#### Utilizando `StreamingResponse` com objetos semelhantes a arquivos { #using-streamingresponse-with-file-like-objects }
Se você tiver um objeto <ahref="https://docs.python.org/3/glossary.html#term-file-like-object"class="external-link"target="_blank">semelhante a um arquivo</a> (e.g. o objeto retornado por `open()`), você pode criar uma função geradora para iterar sobre esse objeto.
Uma tarefa `async` só pode ser cancelada quando alcança um `await`. Se não houver `await`, o gerador (função com `yield`) não pode ser cancelado adequadamente e pode continuar executando mesmo após o cancelamento ser solicitado.
1. Essa é a função geradora. É definida como "função geradora" porque contém declarações `yield` nela.
Como este pequeno exemplo não precisa de nenhuma instrução `await`, adicionamos um `await anyio.sleep(0)` para dar ao event loop a chance de lidar com o cancelamento.
2. Ao utilizar o bloco `with`, nós garantimos que o objeto semelhante a um arquivo é fechado após a função geradora ser finalizada. Isto é, após a resposta terminar de ser enviada.
3. Essa declaração `yield from` informa a função para iterar sobre essa coisa nomeada de `file_like`. E então, para cada parte iterada, fornece essa parte como se viesse dessa função geradora (`iterfile`).
Então, é uma função geradora que transfere o trabalho de "geração" para alguma outra coisa interna.
Isso seria ainda mais importante com streams grandes ou infinitos.
Fazendo dessa forma, podemos colocá-la em um bloco `with`, e assim garantir que o objeto semelhante a um arquivo é fechado quando a função termina.
///
/// tip | Dica
/// tip | Dica
Perceba que aqui estamos utilizando o `open()` da biblioteca padrão que não suporta `async` e `await`, e declaramos a operação de rota com o `def` básico.
Em vez de retornar uma `StreamingResponse` diretamente, você deveria provavelmente seguir o estilo em [Transmitir Dados](./stream-data.md), é muito mais conveniente e lida com cancelamento nos bastidores para você.
Se você estiver transmitindo JSON Lines, siga o tutorial [Transmitir JSON Lines](../tutorial/stream-json-lines.md).
///
///
@ -248,12 +200,12 @@ Envia um arquivo de forma assíncrona e contínua (stream).
Recebe um conjunto de argumentos do construtor diferente dos outros tipos de resposta:
Recebe um conjunto de argumentos do construtor diferente dos outros tipos de resposta:
* `path` - O caminho do arquivo que será transmitido
* `path` - O caminho do arquivo que será transmitido.
* `headers` - quaisquer cabeçalhos que serão incluídos, como um dicionário.
* `headers` - Quaisquer cabeçalhos personalizados a serem incluídos, como um dicionário.
* `media_type` - Uma string com o media type. Se não for definida, o media type é inferido a partir do nome ou caminho do arquivo.
* `media_type` - Uma string com o media type. Se não for definida, o nome do arquivo ou path será usado para inferir um media type.
* `filename` - Se for definido, é incluído no cabeçalho `Content-Disposition`.
* `filename` - Se definido, será incluído no cabeçalho `Content-Disposition`.
Respostas de Arquivos incluem o tamanho do arquivo, data da última modificação e ETags apropriados, nos cabeçalhos `Content-Length`, `Last-Modified` e `ETag`, respectivamente.
Respostas de arquivos incluirão os cabeçalhos apropriados `Content-Length`, `Last-Modified` e `ETag`.
Nesse caso, você pode retornar o caminho do arquivo diretamente da sua *função de operação de rota*.
Nesse caso, você pode retornar o path do arquivo diretamente da sua *função de operação de rota*.
## Classe de resposta personalizada { #custom-response-class }
## Classe de resposta personalizada { #custom-response-class }
Você pode criar sua própria classe de resposta, herdando de `Response` e usando essa nova classe.
Você pode criar sua própria classe de resposta personalizada, herdando de `Response` e usando-a.
Por exemplo, vamos supor que você queira utilizar o <ahref="https://github.com/ijl/orjson"class="external-link"target="_blank">`orjson`</a>, mas com algumas configurações personalizadas que não estão incluídas na classe `ORJSONResponse`.
Por exemplo, vamos supor que você queira usar [`orjson`](https://github.com/ijl/orjson) com algumas configurações.
Vamos supor também que você queira retornar um JSON indentado e formatado, então você quer utilizar a opção `orjson.OPT_INDENT_2` do orjson.
Vamos supor que você queira retornar um JSON indentado e formatado, então você quer utilizar a opção `orjson.OPT_INDENT_2` do orjson.
Você poderia criar uma classe `CustomORJSONResponse`. A principal coisa a ser feita é sobrecarregar o método render da classe Response, `Response.render(content)`, que retorna o conteúdo em bytes:
Você poderia criar uma `CustomORJSONResponse`. A principal coisa que você tem que fazer é criar um método `Response.render(content)` que retorne o conteúdo como `bytes`:
Obviamente, você provavelmente vai encontrar maneiras muito melhores de se aproveitar disso do que a formatação de JSON. 😉
Obviamente, você provavelmente vai encontrar maneiras muito melhores de se aproveitar disso do que a formatação de JSON. 😉
### `orjson` ou Modelo de Resposta { #orjson-or-response-model }
Se o que você procura é performance, provavelmente é melhor usar um [Modelo de Resposta](../tutorial/response-model.md) do que uma resposta com `orjson`.
Com um modelo de resposta, o FastAPI usará o Pydantic para serializar os dados para JSON, sem passos intermediários, como convertê-los com `jsonable_encoder`, o que aconteceria em qualquer outro caso.
E, por baixo dos panos, o Pydantic usa os mesmos mecanismos em Rust que o `orjson` para serializar para JSON, então você já terá a melhor performance com um modelo de resposta.
## Classe de resposta padrão { #default-response-class }
## Classe de resposta padrão { #default-response-class }
Quando você criar uma instância da classe **FastAPI** ou um `APIRouter` você pode especificar qual classe de resposta utilizar por padrão.
Quando você criar uma instância da classe **FastAPI** ou um `APIRouter` você pode especificar qual classe de resposta utilizar por padrão.
O padrão que define isso é o `default_response_class`.
O parâmetro que define isso é o `default_response_class`.
No exemplo abaixo, o **FastAPI** irá utilizar `ORJSONResponse` por padrão, em todas as *operações de rota*, em vez de `JSONResponse`.
No exemplo abaixo, o **FastAPI**utilizará `HTMLResponse` por padrão, em todas as *operações de rota*, em vez de JSON.
Você também pode declarar o media type e muitos outros detalhes no OpenAPI utilizando `responses`: [Retornos Adicionais no OpenAPI](additional-responses.md){.internal-link target=_blank}.
Você também pode declarar o media type e muitos outros detalhes no OpenAPI utilizando `responses`: [Respostas Adicionais no OpenAPI](additional-responses.md).
FastAPI é construído em cima do **Pydantic**, e eu tenho mostrado como usar modelos Pydantic para declarar requisições e respostas.
FastAPI é construído em cima do **Pydantic**, e eu tenho mostrado como usar modelos Pydantic para declarar requisições e respostas.
Mas o FastAPI também suporta o uso de <ahref="https://docs.python.org/3/library/dataclasses.html"class="external-link"target="_blank">`dataclasses`</a> da mesma forma:
Mas o FastAPI também suporta o uso de [`dataclasses`](https://docs.python.org/3/library/dataclasses.html) da mesma forma:
Isso ainda é suportado graças ao **Pydantic**, pois ele tem <ahref="https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel"class="external-link"target="_blank">suporte interno para `dataclasses`</a>.
Isso ainda é suportado graças ao **Pydantic**, pois ele tem [suporte interno para `dataclasses`](https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel).
Então, mesmo com o código acima que não usa Pydantic explicitamente, o FastAPI está usando Pydantic para converter essas dataclasses padrão para a versão do Pydantic.
Então, mesmo com o código acima que não usa Pydantic explicitamente, o FastAPI está usando Pydantic para converter essas dataclasses padrão para a versão do Pydantic.
@ -74,7 +74,7 @@ Nesse caso, você pode simplesmente trocar as `dataclasses` padrão por `pydanti
Como sempre, no FastAPI você pode combinar `def` e `async def` conforme necessário.
Como sempre, no FastAPI você pode combinar `def` e `async def` conforme necessário.
Se você precisar de uma atualização sobre quando usar qual, confira a seção _"Com pressa?"_ na documentação sobre [`async` e `await`](../async.md#in-a-hurry){.internal-link target=_blank}.
Se você precisar de uma atualização sobre quando usar qual, confira a seção _"Com pressa?"_ na documentação sobre [`async` e `await`](../async.md#in-a-hurry).
9. Esta *função de operação de rota* não está retornando dataclasses (embora pudesse), mas uma lista de dicionários com dados internos.
9. Esta *função de operação de rota* não está retornando dataclasses (embora pudesse), mas uma lista de dicionários com dados internos.
@ -88,7 +88,7 @@ Confira as dicas de anotação no código acima para ver mais detalhes específi
Você também pode combinar `dataclasses` com outros modelos Pydantic, herdar deles, incluí-los em seus próprios modelos, etc.
Você também pode combinar `dataclasses` com outros modelos Pydantic, herdar deles, incluí-los em seus próprios modelos, etc.
Para saber mais, confira a <ahref="https://docs.pydantic.dev/latest/concepts/dataclasses/"class="external-link"target="_blank">documentação do Pydantic sobre dataclasses</a>.
Para saber mais, confira a [documentação do Pydantic sobre dataclasses](https://docs.pydantic.dev/latest/concepts/dataclasses/).
Como o **FastAPI** é baseado na especificação **OpenAPI**, suas APIs podem ser descritas em um formato padrão que muitas ferramentas entendem.
Como o **FastAPI** é baseado na especificação **OpenAPI**, suas APIs podem ser descritas em um formato padrão que muitas ferramentas entendem.
Isso facilita gerar **documentação** atualizada, bibliotecas clientes (<abbrtitle="Software Development Kits – Kits de Desenvolvimento de Software">**SDKs**</abbr>) em várias linguagens e **testes** ou **fluxos de trabalho de automação** que permanecem em sincronia com o seu código.
Isso facilita gerar **documentação** atualizada, bibliotecas clientes (<abbrtitle="Software Development Kits - Kits de Desenvolvimento de Software">**SDKs**</abbr>) em várias linguagens e **testes** ou **fluxos de trabalho de automação** que permanecem em sincronia com o seu código.
Neste guia, você aprenderá como gerar um **SDK em TypeScript** para o seu backend FastAPI.
Neste guia, você aprenderá como gerar um **SDK em TypeScript** para o seu backend FastAPI.
## Geradores de SDK de código aberto { #open-source-sdk-generators }
## Geradores de SDK de código aberto { #open-source-sdk-generators }
Uma opção versátil é o <ahref="https://openapi-generator.tech/"class="external-link"target="_blank">OpenAPI Generator</a>, que suporta **muitas linguagens de programação** e pode gerar SDKs a partir da sua especificação OpenAPI.
Uma opção versátil é o [OpenAPI Generator](https://openapi-generator.tech/), que suporta **muitas linguagens de programação** e pode gerar SDKs a partir da sua especificação OpenAPI.
Para **clientes TypeScript**, o <ahref="https://heyapi.dev/"class="external-link"target="_blank">Hey API</a> é uma solução feita sob medida, oferecendo uma experiência otimizada para o ecossistema TypeScript.
Para **clientes TypeScript**, o [Hey API](https://heyapi.dev/) é uma solução feita sob medida, oferecendo uma experiência otimizada para o ecossistema TypeScript.
Você pode descobrir mais geradores de SDK em <ahref="https://openapi.tools/#sdk"class="external-link"target="_blank">OpenAPI.Tools</a>.
Você pode descobrir mais geradores de SDK em [OpenAPI.Tools](https://openapi.tools/#sdk).
/// tip | Dica
/// tip | Dica
@ -24,15 +24,15 @@ O FastAPI gera automaticamente especificações **OpenAPI 3.1**, então qualquer
Esta seção destaca soluções **financiadas por investimento** e **com suporte de empresas** que patrocinam o FastAPI. Esses produtos fornecem **funcionalidades adicionais** e **integrações** além de SDKs gerados com alta qualidade.
Esta seção destaca soluções **financiadas por investimento** e **com suporte de empresas** que patrocinam o FastAPI. Esses produtos fornecem **funcionalidades adicionais** e **integrações** além de SDKs gerados com alta qualidade.
Ao ✨ [**patrocinar o FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨, essas empresas ajudam a garantir que o framework e seu **ecossistema** continuem saudáveis e **sustentáveis**.
Ao ✨ [**patrocinar o FastAPI**](../help-fastapi.md#sponsor-the-author) ✨, essas empresas ajudam a garantir que o framework e seu **ecossistema** continuem saudáveis e **sustentáveis**.
O patrocínio também demonstra um forte compromisso com a **comunidade** FastAPI (você), mostrando que elas se importam não apenas em oferecer um **ótimo serviço**, mas também em apoiar um **framework robusto e próspero**, o FastAPI. 🙇
O patrocínio também demonstra um forte compromisso com a **comunidade** FastAPI (você), mostrando que elas se importam não apenas em oferecer um **ótimo serviço**, mas também em apoiar um **framework robusto e próspero**, o 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. 🤓
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. 🤓
Você pode aprender como <ahref="https://heyapi.dev/openapi-ts/get-started"class="external-link"target="_blank">instalar `@hey-api/openapi-ts`</a> e ler sobre o <ahref="https://heyapi.dev/openapi-ts/output"class="external-link"target="_blank">resultado gerado</a> no site deles.
Você pode aprender como [instalar `@hey-api/openapi-ts`](https://heyapi.dev/openapi-ts/get-started) e ler sobre o [resultado gerado](https://heyapi.dev/openapi-ts/output) no site deles.
O [Tutorial - Guia de Usuário](../tutorial/index.md){.internal-link target=_blank} deve ser o suficiente para dar a você um tour por todos os principais recursos do **FastAPI**.
O [Tutorial - Guia de Usuário](../tutorial/index.md) principal deve ser o suficiente para dar a você um tour por todos os principais recursos do **FastAPI**.
Nas próximas seções você verá outras opções, configurações, e recursos adicionais.
Nas próximas seções você verá outras opções, configurações, e recursos adicionais.
@ -16,6 +16,6 @@ E é possível que para seu caso de uso, a solução esteja em uma delas.
## Leia o Tutorial primeiro { #read-the-tutorial-first }
## Leia o Tutorial primeiro { #read-the-tutorial-first }
Você ainda pode usar a maior parte dos recursos no **FastAPI** com o conhecimento do [Tutorial - Guia de Usuário](../tutorial/index.md){.internal-link target=_blank}.
Você ainda pode usar a maior parte dos recursos no **FastAPI** com o conhecimento do [Tutorial - Guia de Usuário](../tutorial/index.md) principal.
E as próximas seções assumem que você já leu ele, e que você conhece suas ideias principais.
E as próximas seções assumem que você já leu ele, e que você conhece suas ideias principais.
@ -35,7 +35,7 @@ Essa parte é bastante normal, a maior parte do código provavelmente já é fam
/// tip | Dica
/// tip | Dica
O parâmetro de consulta `callback_url` usa um tipo Pydantic <ahref="https://docs.pydantic.dev/latest/api/networks/"class="external-link"target="_blank">Url</a>.
O parâmetro de consulta `callback_url` usa um tipo Pydantic [Url](https://docs.pydantic.dev/latest/api/networks/).
///
///
@ -66,7 +66,7 @@ Esse exemplo não implementa o callback em si (que poderia ser apenas uma linha
O callback real é apenas um request HTTP.
O callback real é apenas um request HTTP.
Ao implementar o callback por conta própria, você pode usar algo como <ahref="https://www.python-httpx.org"class="external-link"target="_blank">HTTPX</a> ou <ahref="https://requests.readthedocs.io/"class="external-link"target="_blank">Requests</a>.
Ao implementar o callback por conta própria, você pode usar algo como [HTTPX](https://www.python-httpx.org) ou [Requests](https://requests.readthedocs.io/).
///
///
@ -106,11 +106,11 @@ Ela deve parecer exatamente como uma *operação de rota* normal do FastAPI:
Há 2 diferenças principais de uma *operação de rota* normal:
Há 2 diferenças principais de uma *operação de rota* normal:
* Ela não necessita ter nenhum código real, porque seu aplicativo nunca chamará esse código. Ele é usado apenas para documentar a *API externa*. Então, a função poderia ter apenas `pass`.
* Ela não necessita ter nenhum código real, porque seu aplicativo nunca chamará esse código. Ele é usado apenas para documentar a *API externa*. Então, a função poderia ter apenas `pass`.
* O *path* pode conter uma <ahref="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression"class="external-link"target="_blank">expressão OpenAPI 3</a> (veja mais abaixo) em que pode usar variáveis com parâmetros e partes do request original enviado para *sua API*.
* O *path* pode conter uma [expressão OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression) (veja mais abaixo) em que pode usar variáveis com parâmetros e partes do request original enviado para *sua API*.
### A expressão do path do callback { #the-callback-path-expression }
### A expressão do path do callback { #the-callback-path-expression }
O *path* do callback pode ter uma <ahref="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression"class="external-link"target="_blank">expressão OpenAPI 3</a> que pode conter partes do request original enviado para *sua API*.
O *path* do callback pode ter uma [expressão OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression) que pode conter partes do request original enviado para *sua API*.
Nesse caso, é a `str`:
Nesse caso, é a `str`:
@ -179,7 +179,7 @@ Perceba que você não está passando o roteador em si (`invoices_callback_route
### Verifique a documentação { #check-the-docs }
### Verifique a documentação { #check-the-docs }
Agora você pode iniciar seu aplicativo e ir para <ahref="http://127.0.0.1:8000/docs"class="external-link"target="_blank">http://127.0.0.1:8000/docs</a>.
Agora você pode iniciar seu aplicativo e ir para [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs).
Você verá sua documentação incluindo uma seção "Callbacks" para sua *operação de rota* que mostra como a *API externa* deveria ser:
Você verá sua documentação incluindo uma seção "Callbacks" para sua *operação de rota* que mostra como a *API externa* deveria ser:
# Retorno - Altere o Código de Status { #response-change-status-code }
# Retorno - Altere o Código de Status { #response-change-status-code }
Você provavelmente leu anteriormente que você pode definir um [Código de Status do Retorno](../tutorial/response-status-code.md){.internal-link target=_blank} padrão.
Você provavelmente leu anteriormente que você pode definir um [Código de Status do Retorno](../tutorial/response-status-code.md) padrão.
Porém em alguns casos você precisa retornar um código de status diferente do padrão.
Porém em alguns casos você precisa retornar um código de status diferente do padrão.
@ -20,7 +20,7 @@ Você também pode declarar o parâmetro `Response` em dependências e definir c
Você também pode criar cookies ao retornar uma `Response` diretamente no seu código.
Você também pode criar cookies ao retornar uma `Response` diretamente no seu código.
Para fazer isso, você pode criar uma resposta como descrito em [Retorne uma Resposta Diretamente](response-directly.md){.internal-link target=_blank}.
Para fazer isso, você pode criar uma resposta como descrito em [Retorne uma Resposta Diretamente](response-directly.md).
Então, defina os cookies nela e a retorne:
Então, defina os cookies nela e a retorne:
@ -48,4 +48,4 @@ E como o `Response` pode ser usado frequentemente para definir cabeçalhos e coo
///
///
Para ver todos os parâmetros e opções disponíveis, verifique a <ahref="https://www.starlette.dev/responses/#set-cookie"class="external-link"target="_blank">documentação no Starlette</a>.
Para ver todos os parâmetros e opções disponíveis, verifique a [documentação no Starlette](https://www.starlette.dev/responses/#set-cookie).
# Retornando uma Resposta Diretamente { #return-a-response-directly }
# Retornando uma Resposta Diretamente { #return-a-response-directly }
Quando você cria uma *operação de rota* no **FastAPI** você pode retornar qualquer dado nela: um dicionário (`dict`), uma lista (`list`), um modelo do Pydantic ou do seu banco de dados, etc.
Quando você cria uma *operação de rota* no **FastAPI**, normalmente você pode retornar qualquer dado: um `dict`, uma `list`, um modelo do Pydantic, um modelo do banco de dados, etc.
Por padrão, o **FastAPI** irá converter automaticamente o valor do retorno para JSON utilizando o `jsonable_encoder` explicado em [Codificador Compatível com JSON](../tutorial/encoder.md){.internal-link target=_blank}.
Se você declarar um [Modelo de resposta](../tutorial/response-model.md), o FastAPI irá usá-lo para serializar os dados para JSON, usando o Pydantic.
Então, por baixo dos panos, ele incluiria esses dados compatíveis com JSON (e.g. um `dict`) dentro de uma `JSONResponse` que é utilizada para enviar uma resposta para o cliente.
Se você não declarar um modelo de resposta, o FastAPI usará o `jsonable_encoder` explicado em [Codificador Compatível com JSON](../tutorial/encoder.md) e o colocará em uma `JSONResponse`.
Mas você pode retornar a `JSONResponse` diretamente nas suas *operações de rota*.
Você também pode criar uma `JSONResponse` diretamente e retorná-la.
Pode ser útil para retornar cabeçalhos e cookies personalizados, por exemplo.
/// tip | Dica
Normalmente você terá um desempenho muito melhor usando um [Modelo de resposta](../tutorial/response-model.md) do que retornando uma `JSONResponse` diretamente, pois assim ele serializa os dados usando o Pydantic, em Rust.
///
## Retornando uma `Response` { #return-a-response }
## Retornando uma `Response` { #return-a-response }
Na verdade, você pode retornar qualquer `Response` ou subclasse dela.
Você pode retornar uma `Response` ou qualquer subclasse dela.
/// tip | Dica
/// info | Informação
A própria `JSONResponse` é uma subclasse de `Response`.
A própria `JSONResponse` é uma subclasse de `Response`.
@ -22,10 +26,12 @@ A própria `JSONResponse` é uma subclasse de `Response`.
E quando você retorna uma `Response`, o **FastAPI** vai repassá-la diretamente.
E quando você retorna uma `Response`, o **FastAPI** vai repassá-la diretamente.
Ele não vai fazer conversões de dados com modelos do Pydantic, não irá converter a tipagem de nenhum conteúdo, etc.
Ele não fará conversões de dados com modelos do Pydantic, não converterá o conteúdo para nenhum tipo, etc.
Isso te dá bastante flexibilidade. Você pode retornar qualquer tipo de dado, sobrescrever qualquer declaração e validação nos dados, etc.
Isso te dá bastante flexibilidade. Você pode retornar qualquer tipo de dado, sobrescrever qualquer declaração e validação nos dados, etc.
Isso também te dá muita responsabilidade. Você precisa garantir que os dados retornados estão corretos, no formato correto, que podem ser serializados, etc.
## Utilizando o `jsonable_encoder` em uma `Response` { #using-the-jsonable-encoder-in-a-response }
## Utilizando o `jsonable_encoder` em uma `Response` { #using-the-jsonable-encoder-in-a-response }
Como o **FastAPI** não realiza nenhuma mudança na `Response` que você retorna, você precisa garantir que o conteúdo dela está pronto para uso.
Como o **FastAPI** não realiza nenhuma mudança na `Response` que você retorna, você precisa garantir que o conteúdo dela está pronto para uso.
@ -50,16 +56,28 @@ O exemplo acima mostra todas as partes que você precisa, mas ainda não é muit
Agora, vamos ver como você pode usar isso para retornar uma resposta personalizada.
Agora, vamos ver como você pode usar isso para retornar uma resposta personalizada.
Vamos dizer que você quer retornar uma resposta <ahref="https://en.wikipedia.org/wiki/XML"class="external-link"target="_blank">XML</a>.
Vamos dizer que você quer retornar uma resposta [XML](https://en.wikipedia.org/wiki/XML).
Você pode colocar o seu conteúdo XML em uma string, colocar em uma `Response`, e retorná-lo:
Você pode colocar o seu conteúdo XML em uma string, colocar em uma `Response`, e retorná-lo:
## Como funciona um Modelo de resposta { #how-a-response-model-works }
Quando você declara um [Modelo de resposta - Tipo de retorno](../tutorial/response-model.md) em uma operação de rota, o **FastAPI** irá usá-lo para serializar os dados para JSON, usando o Pydantic.
Como isso acontece no lado do Rust, o desempenho será muito melhor do que se fosse feito com Python comum e a classe `JSONResponse`.
Ao usar um `response_model` ou tipo de retorno, o FastAPI não usará o `jsonable_encoder` para converter os dados (o que seria mais lento) nem a classe `JSONResponse`.
Em vez disso, ele pega os bytes JSON gerados com o Pydantic usando o modelo de resposta (ou tipo de retorno) e retorna uma `Response` com o media type correto para JSON diretamente (`application/json`).
## Notas { #notes }
## Notas { #notes }
Quando você retorna uma `Response` diretamente os dados não são validados, convertidos (serializados) ou documentados automaticamente.
Quando você retorna uma `Response` diretamente os dados não são validados, convertidos (serializados) ou documentados automaticamente.
Mas você ainda pode documentar como descrito em [Retornos Adicionais no OpenAPI](additional-responses.md){.internal-link target=_blank}.
Mas você ainda pode documentar como descrito em [Respostas adicionais no OpenAPI](additional-responses.md).
Você pode ver nas próximas seções como usar/declarar essas `Responses` customizadas enquanto mantém a conversão e documentação automática dos dados.
Você pode ver nas próximas seções como usar/declarar essas `Responses` customizadas enquanto mantém a conversão e documentação automática dos dados.
@ -20,7 +20,7 @@ Você também pode declarar o parâmetro `Response` em dependências e definir c
Você também pode adicionar cabeçalhos quando retornar uma `Response` diretamente.
Você também pode adicionar cabeçalhos quando retornar uma `Response` diretamente.
Crie uma resposta conforme descrito em [Retornar uma resposta diretamente](response-directly.md){.internal-link target=_blank} e passe os cabeçalhos como um parâmetro adicional:
Crie uma resposta conforme descrito em [Retornar uma resposta diretamente](response-directly.md) e passe os cabeçalhos como um parâmetro adicional:
@ -36,6 +36,6 @@ E como a `Response` pode ser usada frequentemente para definir cabeçalhos e coo
## Cabeçalhos personalizados { #custom-headers }
## Cabeçalhos personalizados { #custom-headers }
Tenha em mente que cabeçalhos personalizados proprietários podem ser adicionados <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers"class="external-link"target="_blank">usando o prefixo `X-`</a>.
Tenha em mente que cabeçalhos personalizados proprietários podem ser adicionados [usando o prefixo `X-`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers).
Porém, se você tiver cabeçalhos personalizados que deseja que um cliente no navegador possa ver, você precisa adicioná-los às suas configurações de CORS (saiba mais em [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md){.internal-link target=_blank}), usando o parâmetro `expose_headers` descrito na <ahref="https://www.starlette.dev/middleware/#corsmiddleware"class="external-link"target="_blank">documentação de CORS do Starlette</a>.
Porém, se você tiver cabeçalhos personalizados que deseja que um cliente no navegador possa ver, você precisa adicioná-los às suas configurações de CORS (saiba mais em [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md)), usando o parâmetro `expose_headers` descrito na [documentação de CORS do Starlette](https://www.starlette.dev/middleware/#corsmiddleware).
@ -32,7 +32,7 @@ Aqui está um exemplo mais completo.
Utilize uma dependência para verificar se o usuário e a senha estão corretos.
Utilize uma dependência para verificar se o usuário e a senha estão corretos.
Para isso, utilize o módulo padrão do Python <ahref="https://docs.python.org/3/library/secrets.html"class="external-link"target="_blank">`secrets`</a> para verificar o usuário e senha.
Para isso, utilize o módulo padrão do Python [`secrets`](https://docs.python.org/3/library/secrets.html) para verificar o usuário e senha.
O `secrets.compare_digest()` necessita receber `bytes` ou `str` que possuem apenas caracteres ASCII (os em inglês). Isso significa que não funcionaria com caracteres como o `á`, como em `Sebastián`.
O `secrets.compare_digest()` necessita receber `bytes` ou `str` que possuem apenas caracteres ASCII (os em inglês). Isso significa que não funcionaria com caracteres como o `á`, como em `Sebastián`.
@ -50,11 +50,11 @@ if not (credentials.username == "stanleyjobson") or not (credentials.password ==
...
...
```
```
Porém, ao utilizar o `secrets.compare_digest()`, isso estará seguro contra um tipo de ataque chamado "timing attacks" (ataques de temporização).
Porém, ao utilizar o `secrets.compare_digest()`, isso estará seguro contra um tipo de ataque chamado "timing attacks".
### Ataques de Temporização { #timing-attacks }
### Ataques de Temporização { #timing-attacks }
Mas o que é um "timing attack" (ataque de temporização)?
Mas o que é um "timing attack"?
Vamos imaginar que alguns invasores estão tentando adivinhar o usuário e a senha.
Vamos imaginar que alguns invasores estão tentando adivinhar o usuário e a senha.
Existem algumas funcionalidades adicionais para lidar com segurança além das cobertas em [Tutorial - Guia de Usuário: Segurança](../../tutorial/security/index.md){.internal-link target=_blank}.
Existem algumas funcionalidades adicionais para lidar com segurança além das cobertas em [Tutorial - Guia de Usuário: Segurança](../../tutorial/security/index.md).
/// tip | Dica
/// tip | Dica
@ -14,6 +14,6 @@ E é possível que para o seu caso de uso, a solução está em uma delas.
## Leia o Tutorial primeiro { #read-the-tutorial-first }
## Leia o Tutorial primeiro { #read-the-tutorial-first }
As próximas seções pressupõem que você já leu o principal [Tutorial - Guia de Usuário: Segurança](../../tutorial/security/index.md){.internal-link target=_blank}.
As próximas seções pressupõem que você já leu o principal [Tutorial - Guia de Usuário: Segurança](../../tutorial/security/index.md).
Todas elas são baseadas nos mesmos conceitos, mas permitem algumas funcionalidades extras.
Todas elas são baseadas nos mesmos conceitos, mas permitem algumas funcionalidades extras.
@ -60,7 +60,7 @@ Para o OAuth2, eles são apenas strings.
## Visão global { #global-view }
## Visão global { #global-view }
Primeiro, vamos olhar rapidamente as partes que mudam dos exemplos do **Tutorial - Guia de Usuário** para [OAuth2 com Senha (e hash), Bearer com tokens JWT](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank}. Agora utilizando escopos OAuth2:
Primeiro, vamos olhar rapidamente as partes que mudam dos exemplos do **Tutorial - Guia de Usuário** para [OAuth2 com Senha (e hash), Bearer com tokens JWT](../../tutorial/security/oauth2-jwt.md). Agora utilizando escopos OAuth2:
`Security` é na verdade uma subclasse de `Depends`, e ele possui apenas um parâmetro extra que veremos depois.
`Security` é na verdade uma subclasse de `Depends`, e ele possui apenas um parâmetro extra que veremos depois.
@ -271,4 +271,4 @@ O **FastAPI** inclui utilitários para todos esses fluxos de autenticação OAut
## `Security` em decoradores de `dependencies` { #security-in-decorator-dependencies }
## `Security` em decoradores de `dependencies` { #security-in-decorator-dependencies }
Da mesma forma que você pode definir uma `list` de `Depends` no parâmetro `dependencies` do decorador (como explicado em [Dependências em decoradores de operações de rota](../../tutorial/dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}), você também pode utilizar `Security` com escopos lá.
Da mesma forma que você pode definir uma `list` de `Depends` no parâmetro `dependencies` do decorador (como explicado em [Dependências em decoradores de operações de rota](../../tutorial/dependencies/dependencies-in-path-operation-decorators.md)), você também pode utilizar `Security` com escopos lá.
E então, abra a documentação para a sub-aplicação, em <ahref="http://127.0.0.1:8000/subapi/docs"class="external-link"target="_blank">http://127.0.0.1:8000/subapi/docs</a>.
E então, abra a documentação para a sub-aplicação, em [http://127.0.0.1:8000/subapi/docs](http://127.0.0.1:8000/subapi/docs).
Você verá a documentação automática da API para a sub-aplicação, incluindo apenas suas próprias _operações de rota_, todas sob o prefixo de sub-path correto `/subapi`:
Você verá a documentação automática da API para a sub-aplicação, incluindo apenas suas próprias _operações de rota_, todas sob o prefixo de sub-path correto `/subapi`:
@ -64,4 +64,4 @@ Dessa forma, a sub-aplicação saberá usar esse prefixo de path para a interfac
E a sub-aplicação também poderia ter suas próprias sub-aplicações montadas e tudo funcionaria corretamente, porque o FastAPI lida com todos esses `root_path`s automaticamente.
E a sub-aplicação também poderia ter suas próprias sub-aplicações montadas e tudo funcionaria corretamente, porque o FastAPI lida com todos esses `root_path`s automaticamente.
Você aprenderá mais sobre o `root_path` e como usá-lo explicitamente na seção sobre [Atrás de um Proxy](behind-a-proxy.md){.internal-link target=_blank}.
Você aprenderá mais sobre o `root_path` e como usá-lo explicitamente na seção sobre [Atrás de um Proxy](behind-a-proxy.md).
@ -15,7 +15,7 @@ Porém há situações em que você possa precisar acessar o objeto `Request` di
## Detalhes sobre o objeto `Request` { #details-about-the-request-object }
## Detalhes sobre o objeto `Request` { #details-about-the-request-object }
Como o **FastAPI** é na verdade o **Starlette** por baixo, com camadas de diversas funcionalidades por cima, você pode utilizar o objeto <ahref="https://www.starlette.dev/requests/"class="external-link"target="_blank">`Request`</a> do Starlette diretamente quando precisar.
Como o **FastAPI** é na verdade o **Starlette** por baixo, com camadas de diversas funcionalidades por cima, você pode utilizar o objeto [`Request`](https://www.starlette.dev/requests/) do Starlette diretamente quando precisar.
Isso significaria também que se você obtiver informações do objeto `Request` diretamente (ler o corpo da requisição por exemplo), as informações não serão validadas, convertidas ou documentadas (com o OpenAPI, para a interface de usuário automática da API) pelo FastAPI.
Isso significaria também que se você obtiver informações do objeto `Request` diretamente (ler o corpo da requisição por exemplo), as informações não serão validadas, convertidas ou documentadas (com o OpenAPI, para a interface de usuário automática da API) pelo FastAPI.
@ -45,7 +45,7 @@ Do mesmo jeito, você pode declarar qualquer outro parâmetro normalmente, e al
## Documentação do `Request` { #request-documentation }
## Documentação do `Request` { #request-documentation }
Você pode ler mais sobre os detalhes do objeto <ahref="https://www.starlette.dev/requests/"class="external-link"target="_blank">`Request` no site da documentação oficial do Starlette.</a>.
Você pode ler mais sobre os detalhes do [objeto `Request` no site da documentação oficial do Starlette](https://www.starlette.dev/requests/).
@ -6,7 +6,7 @@ Na maioria dos casos, os principais provedores de nuvem têm tutoriais para impl
## FastAPI Cloud { #fastapi-cloud }
## FastAPI Cloud { #fastapi-cloud }
**<ahref="https://fastapicloud.com"class="external-link"target="_blank">FastAPI Cloud</a>** é desenvolvido pelo mesmo autor e equipe por trás do **FastAPI**.
**[FastAPI Cloud](https://fastapicloud.com)** é desenvolvido pelo mesmo autor e equipe por trás do **FastAPI**.
Ele simplifica o processo de **criar**, **implantar** e **acessar** uma API com o mínimo de esforço.
Ele simplifica o processo de **criar**, **implantar** e **acessar** uma API com o mínimo de esforço.
@ -16,9 +16,9 @@ FastAPI Cloud é o patrocinador principal e provedor de financiamento dos projet
## Provedores de Nuvem - Patrocinadores { #cloud-providers-sponsors }
## Provedores de Nuvem - Patrocinadores { #cloud-providers-sponsors }
Alguns outros provedores de nuvem ✨ [**patrocinam o FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨ também. 🙇
Alguns outros provedores de nuvem ✨ [**patrocinam o FastAPI**](../help-fastapi.md#sponsor-the-author) ✨ também. 🙇
Você também pode considerá-los para seguir seus tutoriais e experimentar seus serviços:
Você também pode considerá-los para seguir seus tutoriais e experimentar seus serviços:
@ -25,7 +25,7 @@ Mas por enquanto, vamos verificar essas importantes **ideias conceituais**. Esse
## Segurança - HTTPS { #security-https }
## Segurança - HTTPS { #security-https }
No [capítulo anterior sobre HTTPS](https.md){.internal-link target=_blank} aprendemos como o HTTPS fornece criptografia para sua API.
No [capítulo anterior sobre HTTPS](https.md) aprendemos como o HTTPS fornece criptografia para sua API.
Também vimos que o HTTPS normalmente é fornecido por um componente **externo** ao seu servidor de aplicativos, um **Proxy de terminação TLS**.
Também vimos que o HTTPS normalmente é fornecido por um componente **externo** ao seu servidor de aplicativos, um **Proxy de terminação TLS**.
@ -145,7 +145,7 @@ O cliente receberá um **Erro Interno do Servidor 500** para essa solicitação,
No entanto, pode haver casos em que escrevemos algum código que **trava todo o aplicativo**, fazendo com que o Uvicorn e o Python travem. 💥
No entanto, pode haver casos em que escrevemos algum código que **trava todo o aplicativo**, fazendo com que o Uvicorn e o Python travem. 💥
E ainda assim, você provavelmente não gostaria que o aplicativo permanecesse inativo porque houve um erro em um lugar, você provavelmente quer que ele **continue em execução** pelo menos para as *operações de caminho* que não estão quebradas.
E ainda assim, você provavelmente não gostaria que o aplicativo permanecesse inativo porque houve um erro em um lugar, você provavelmente quer que ele **continue em execução** pelo menos para as *operações de rota* que não estão quebradas.
### Reiniciar após falha { #restart-after-crash }
### Reiniciar após falha { #restart-after-crash }
@ -190,7 +190,7 @@ Quando você executa **vários processos** do mesmo programa de API, eles são c
### Processos do Trabalhador e Portas { #worker-processes-and-ports }
### Processos do Trabalhador e Portas { #worker-processes-and-ports }
Lembra da documentação [Sobre HTTPS](https.md){.internal-link target=_blank} que diz que apenas um processo pode escutar em uma combinação de porta e endereço IP em um servidor?
Lembra da documentação [Sobre HTTPS](https.md) que diz que apenas um processo pode escutar em uma combinação de porta e endereço IP em um servidor?
Isso ainda é verdade.
Isso ainda é verdade.
@ -204,7 +204,7 @@ E vários processos normalmente **não compartilham nenhuma memória**. Isso sig
### Memória do servidor { #server-memory }
### Memória do servidor { #server-memory }
Por exemplo, se seu código carrega um modelo de Machine Learning com **1 GB de tamanho**, quando você executa um processo com sua API, ele consumirá pelo menos 1 GB de RAM. E se você iniciar **4 processos** (4 trabalhadores), cada um consumirá 1 GB de RAM. Então, no total, sua API consumirá **4 GB de RAM**.
Por exemplo, se seu código carrega um modelo de Aprendizado de Máquina com **1 GB de tamanho**, quando você executa um processo com sua API, ele consumirá pelo menos 1 GB de RAM. E se você iniciar **4 processos** (4 trabalhadores), cada um consumirá 1 GB de RAM. Então, no total, sua API consumirá **4 GB de RAM**.
E se o seu servidor remoto ou máquina virtual tiver apenas 3 GB de RAM, tentar carregar mais de 4 GB de RAM causará problemas. 🚨
E se o seu servidor remoto ou máquina virtual tiver apenas 3 GB de RAM, tentar carregar mais de 4 GB de RAM causará problemas. 🚨
@ -243,7 +243,7 @@ Aqui estão algumas combinações e estratégias possíveis:
Não se preocupe se alguns desses itens sobre **contêineres**, Docker ou Kubernetes ainda não fizerem muito sentido.
Não se preocupe se alguns desses itens sobre **contêineres**, Docker ou Kubernetes ainda não fizerem muito sentido.
Falarei mais sobre imagens de contêiner, Docker, Kubernetes, etc. em um capítulo futuro: [FastAPI em contêineres - Docker](docker.md){.internal-link target=_blank}.
Falarei mais sobre imagens de contêiner, Docker, Kubernetes, etc. em um capítulo futuro: [FastAPI em contêineres - Docker](docker.md).
///
///
@ -281,7 +281,7 @@ Aqui estão algumas ideias possíveis:
/// tip | Dica
/// tip | Dica
Darei exemplos mais concretos de como fazer isso com contêineres em um capítulo futuro: [FastAPI em contêineres - Docker](docker.md){.internal-link target=_blank}.
Darei exemplos mais concretos de como fazer isso com contêineres em um capítulo futuro: [FastAPI em contêineres - Docker](docker.md).
# FastAPI em contêineres - Docker { #fastapi-in-containers-docker }
# FastAPI em contêineres - Docker { #fastapi-in-containers-docker }
Ao fazer o deploy de aplicações FastAPI uma abordagem comum é construir uma **imagem de contêiner Linux**. Isso normalmente é feito usando o <ahref="https://www.docker.com/"class="external-link"target="_blank">**Docker**</a>. Você pode a partir disso fazer o deploy dessa imagem de algumas maneiras.
Ao fazer o deploy de aplicações FastAPI uma abordagem comum é construir uma **imagem de contêiner Linux**. Isso normalmente é feito usando o [**Docker**](https://www.docker.com/). Você pode a partir disso fazer o deploy dessa imagem de algumas maneiras.
Usando contêineres Linux você tem diversas vantagens incluindo **segurança**, **replicabilidade**, **simplicidade**, entre outras.
Usando contêineres Linux você tem diversas vantagens incluindo **segurança**, **replicabilidade**, **simplicidade**, entre outras.
@ -60,16 +60,16 @@ E o **contêiner** em si (em contraste à **imagem de contêiner**) é a própri
Docker tem sido uma das principais ferramentas para criar e gerenciar **imagens de contêiner** e **contêineres**.
Docker tem sido uma das principais ferramentas para criar e gerenciar **imagens de contêiner** e **contêineres**.
E existe um <ahref="https://hub.docker.com/"class="external-link"target="_blank">Docker Hub</a> público com **imagens de contêiner oficiais** pré-prontas para diversas ferramentas, ambientes, bancos de dados e aplicações.
E existe um [Docker Hub](https://hub.docker.com/) público com **imagens de contêiner oficiais** pré-prontas para diversas ferramentas, ambientes, bancos de dados e aplicações.
Por exemplo, há uma <ahref="https://hub.docker.com/_/python"class="external-link"target="_blank">Imagem Python</a> oficial.
Por exemplo, há uma [Imagem Python](https://hub.docker.com/_/python) oficial.
E existe muitas outras imagens para diferentes coisas, como bancos de dados, por exemplo:
E existe muitas outras imagens para diferentes coisas, como bancos de dados, por exemplo:
* <ahref="https://hub.docker.com/_/redis"class="external-link"target="_blank">Redis</a>, etc.
* [Redis](https://hub.docker.com/_/redis), etc.
Usando imagens de contêiner pré-prontas é muito fácil **combinar** e usar diferentes ferramentas. Por exemplo, para testar um novo banco de dados. Em muitos casos, você pode usar as **imagens oficiais**, precisando somente de variáveis de ambiente para configurá-las.
Usando imagens de contêiner pré-prontas é muito fácil **combinar** e usar diferentes ferramentas. Por exemplo, para testar um novo banco de dados. Em muitos casos, você pode usar as **imagens oficiais**, precisando somente de variáveis de ambiente para configurá-las.
@ -111,7 +111,7 @@ Isso pode depender principalmente da ferramenta que você usa para **instalar**
A forma mais comum de fazer isso é ter um arquivo `requirements.txt` com os nomes dos pacotes e suas versões, um por linha.
A forma mais comum de fazer isso é ter um arquivo `requirements.txt` com os nomes dos pacotes e suas versões, um por linha.
Você, naturalmente, usaria as mesmas ideias que você leu em [Sobre versões do FastAPI](versions.md){.internal-link target=_blank} para definir os intervalos de versões.
Você, naturalmente, usaria as mesmas ideias que você leu em [Sobre versões do FastAPI](versions.md) para definir os intervalos de versões.
Por exemplo, seu `requirements.txt` poderia parecer com:
Por exemplo, seu `requirements.txt` poderia parecer com:
@ -238,7 +238,7 @@ Certifique-se de **sempre** usar a **forma exec** da instrução `CMD`, como exp
#### Use `CMD` - Forma Exec { #use-cmd-exec-form }
#### Use `CMD` - Forma Exec { #use-cmd-exec-form }
A instrução <ahref="https://docs.docker.com/reference/dockerfile/#cmd"class="external-link"target="_blank">`CMD`</a> no Docker pode ser escrita de duas formas:
A instrução [`CMD`](https://docs.docker.com/reference/dockerfile/#cmd) no Docker pode ser escrita de duas formas:
Garanta que você sempre use a forma **exec** para assegurar que o FastAPI consiga encerrar graciosamente e que os [eventos de lifespan](../advanced/events.md){.internal-link target=_blank} sejam disparados.
Garanta que você sempre use a forma **exec** para assegurar que o FastAPI consiga encerrar graciosamente e que os [eventos de lifespan](../advanced/events.md) sejam disparados.
Você pode ler mais na <ahref="https://docs.docker.com/reference/dockerfile/#shell-and-exec-form"class="external-link"target="_blank">documentação do Docker sobre as formas shell e exec</a>.
Você pode ler mais na [documentação do Docker sobre as formas shell e exec](https://docs.docker.com/reference/dockerfile/#shell-and-exec-form).
Isso pode ser bem perceptível ao usar `docker compose`. Veja esta seção de FAQ do Docker Compose para mais detalhes técnicos: <ahref="https://docs.docker.com/compose/faq/#why-do-my-services-take-10-seconds-to-recreate-or-stop"class="external-link"target="_blank">Por que meus serviços demoram 10 segundos para recriar ou parar?</a>.
Isso pode ser bem perceptível ao usar `docker compose`. Veja esta seção de FAQ do Docker Compose para mais detalhes técnicos: [Por que meus serviços demoram 10 segundos para recriar ou parar?](https://docs.docker.com/compose/faq/#why-do-my-services-take-10-seconds-to-recreate-or-stop).
#### Estrutura de diretórios { #directory-structure }
#### Estrutura de diretórios { #directory-structure }
Você deve ser capaz de verificar isso no URL do seu contêiner Docker, por exemplo: <ahref="http://192.168.99.100/items/5?q=somequery"class="external-link"target="_blank">http://192.168.99.100/items/5?q=somequery</a> ou <ahref="http://127.0.0.1/items/5?q=somequery"class="external-link"target="_blank">http://127.0.0.1/items/5?q=somequery</a> (ou equivalente, usando seu host Docker).
Você deve ser capaz de verificar isso no URL do seu contêiner Docker, por exemplo: [http://192.168.99.100/items/5?q=somequery](http://192.168.99.100/items/5?q=somequery) ou [http://127.0.0.1/items/5?q=somequery](http://127.0.0.1/items/5?q=somequery) (ou equivalente, usando seu host Docker).
Você verá algo como:
Você verá algo como:
@ -362,17 +362,17 @@ Você verá algo como:
## Documentação interativa da API { #interactive-api-docs }
## Documentação interativa da API { #interactive-api-docs }
Agora você pode ir para <ahref="http://192.168.99.100/docs"class="external-link"target="_blank">http://192.168.99.100/docs</a> ou <ahref="http://127.0.0.1/docs"class="external-link"target="_blank">http://127.0.0.1/docs</a> (ou equivalente, usando seu host Docker).
Agora você pode ir para [http://192.168.99.100/docs](http://192.168.99.100/docs) ou [http://127.0.0.1/docs](http://127.0.0.1/docs) (ou equivalente, usando seu host Docker).
Você verá a documentação interativa automática da API (fornecida pelo <ahref="https://github.com/swagger-api/swagger-ui"class="external-link"target="_blank">Swagger UI</a>):
Você verá a documentação interativa automática da API (fornecida pelo [Swagger UI](https://github.com/swagger-api/swagger-ui)):
## Documentação alternativa da API { #alternative-api-docs }
## Documentação alternativa da API { #alternative-api-docs }
E você também pode ir para <ahref="http://192.168.99.100/redoc"class="external-link"target="_blank">http://192.168.99.100/redoc</a> ou <ahref="http://127.0.0.1/redoc"class="external-link"target="_blank">http://127.0.0.1/redoc</a> (ou equivalente, usando seu host Docker).
E você também pode ir para [http://192.168.99.100/redoc](http://192.168.99.100/redoc) ou [http://127.0.0.1/redoc](http://127.0.0.1/redoc) (ou equivalente, usando seu host Docker).
Você verá a documentação alternativa automática (fornecida pela <ahref="https://github.com/Rebilly/ReDoc"class="external-link"target="_blank">ReDoc</a>):
Você verá a documentação alternativa automática (fornecida pelo [ReDoc](https://github.com/Rebilly/ReDoc)):
@ -413,7 +413,7 @@ Quando você passa o arquivo para `fastapi run` ele detecta automaticamente que
## Conceitos de Implantação { #deployment-concepts }
## Conceitos de Implantação { #deployment-concepts }
Vamos falar novamente sobre alguns dos mesmos [Conceitos de Implantação](concepts.md){.internal-link target=_blank} em termos de contêineres.
Vamos falar novamente sobre alguns dos mesmos [Conceitos de Implantação](concepts.md) em termos de contêineres.
Contêineres são principalmente uma ferramenta para simplificar o processo de **construção e implantação** de um aplicativo, mas eles não impõem uma abordagem particular para lidar com esses **conceitos de implantação** e existem várias estratégias possíveis.
Contêineres são principalmente uma ferramenta para simplificar o processo de **construção e implantação** de um aplicativo, mas eles não impõem uma abordagem particular para lidar com esses **conceitos de implantação** e existem várias estratégias possíveis.
@ -432,7 +432,7 @@ Vamos revisar esses **conceitos de implantação** em termos de contêineres:
Se nos concentrarmos apenas na **imagem do contêiner** para um aplicativo FastAPI (e posteriormente no **contêiner** em execução), o HTTPS normalmente seria tratado **externamente** por outra ferramenta.
Se nos concentrarmos apenas na **imagem do contêiner** para um aplicativo FastAPI (e posteriormente no **contêiner** em execução), o HTTPS normalmente seria tratado **externamente** por outra ferramenta.
Isso poderia ser outro contêiner, por exemplo, com <ahref="https://traefik.io/"class="external-link"target="_blank">Traefik</a>, lidando com **HTTPS** e aquisição **automática** de **certificados**.
Isso poderia ser outro contêiner, por exemplo, com [Traefik](https://traefik.io/), lidando com **HTTPS** e aquisição **automática** de **certificados**.
/// tip | Dica
/// tip | Dica
@ -558,7 +558,7 @@ Se você tiver **múltiplos contêineres**, provavelmente cada um executando um
/// info | Informação
/// info | Informação
Se você estiver usando o Kubernetes, provavelmente será um <ahref="https://kubernetes.io/docs/concepts/workloads/pods/init-containers/"class="external-link"target="_blank">Init Container</a>.
Se você estiver usando o Kubernetes, provavelmente será um [Init Container](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/).
///
///
@ -570,7 +570,7 @@ Se você tiver uma configuração simples, com um **único contêiner** que ent
### Imagem Docker base { #base-docker-image }
### Imagem Docker base { #base-docker-image }
Antes havia uma imagem oficial do FastAPI para Docker: <ahref="https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker"class="external-link"target="_blank">tiangolo/uvicorn-gunicorn-fastapi</a>. Mas agora ela está descontinuada. ⛔️
Antes havia uma imagem oficial do FastAPI para Docker: [tiangolo/uvicorn-gunicorn-fastapi](https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker). Mas agora ela está descontinuada. ⛔️
Você provavelmente **não** deve usar essa imagem base do Docker (ou qualquer outra semelhante).
Você provavelmente **não** deve usar essa imagem base do Docker (ou qualquer outra semelhante).
@ -600,7 +600,7 @@ Por exemplo:
## Imagem Docker com `uv` { #docker-image-with-uv }
## Imagem Docker com `uv` { #docker-image-with-uv }
Se você está usando o <ahref="https://github.com/astral-sh/uv"class="external-link"target="_blank">uv</a> para instalar e gerenciar seu projeto, você pode seguir o <ahref="https://docs.astral.sh/uv/guides/integration/docker/"class="external-link"target="_blank">guia de Docker do uv</a>.
Se você está usando o [uv](https://github.com/astral-sh/uv) para instalar e gerenciar seu projeto, você pode seguir o [guia de Docker do uv](https://docs.astral.sh/uv/guides/integration/docker/).
Você pode implantar sua aplicação FastAPI no <ahref="https://fastapicloud.com"class="external-link"target="_blank">FastAPI Cloud</a> com um **único comando**; entre na lista de espera, caso ainda não tenha feito isso. 🚀
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 }
## Login { #login }
@ -40,7 +40,7 @@ Deploying to FastAPI Cloud...
## Sobre o FastAPI Cloud { #about-fastapi-cloud }
## Sobre o FastAPI Cloud { #about-fastapi-cloud }
O **<ahref="https://fastapicloud.com"class="external-link"target="_blank">FastAPI Cloud</a>** é desenvolvido pelo mesmo autor e equipe por trás do **FastAPI**.
O **[FastAPI Cloud](https://fastapicloud.com)** é desenvolvido pelo mesmo autor e equipe por trás do **FastAPI**.
Ele simplifica o processo de **criar**, **implantar** e **acessar** uma API com esforço mínimo.
Ele simplifica o processo de **criar**, **implantar** e **acessar** uma API com esforço mínimo.
@ -10,7 +10,7 @@ Se você está com pressa ou não se importa, continue com as seções seguintes
///
///
Para aprender o básico de HTTPS do ponto de vista do consumidor, verifique <ahref="https://howhttps.works/"class="external-link"target="_blank">https://howhttps.works/</a>.
Para aprender o básico de HTTPS do ponto de vista do consumidor, verifique [https://howhttps.works/](https://howhttps.works/).
Agora, a partir de uma perspectiva do desenvolvedor, aqui estão algumas coisas para ter em mente ao pensar em HTTPS:
Agora, a partir de uma perspectiva do desenvolvedor, aqui estão algumas coisas para ter em mente ao pensar em HTTPS:
@ -28,13 +28,13 @@ Agora, a partir de uma perspectiva do desenvolvedor, aqui estão algumas coisas
* Por padrão, isso significa que você só pode ter um certificado HTTPS por endereço IP.
* Por padrão, isso significa que você só pode ter um certificado HTTPS por endereço IP.
* Não importa o tamanho do seu servidor ou quão pequeno cada aplicativo que você tem nele possa ser.
* Não importa o tamanho do seu servidor ou quão pequeno cada aplicativo que você tem nele possa ser.
* No entanto, existe uma solução para isso.
* No entanto, existe uma solução para isso.
* Há uma extensão para o protocolo TLS (aquele que lida com a criptografia no nível TCP, antes do HTTP) chamada <ahref="https://en.wikipedia.org/wiki/Server_Name_Indication"class="external-link"target="_blank"><abbrtitle="Server Name Indication - Indicação do Nome do Servidor">SNI</abbr></a>.
* Há uma extensão para o protocolo TLS (aquele que lida com a criptografia no nível TCP, antes do HTTP) chamada [<abbr title="Server Name Indication - Indicação do Nome do Servidor">SNI</abbr>](https://en.wikipedia.org/wiki/Server_Name_Indication).
* Esta extensão SNI permite que um único servidor (com um único endereço IP) tenha vários certificados HTTPS e atenda a vários domínios / aplicativos HTTPS.
* Esta extensão SNI permite que um único servidor (com um único endereço IP) tenha vários certificados HTTPS e atenda a vários domínios / aplicativos HTTPS.
* Para que isso funcione, um único componente (programa) em execução no servidor, ouvindo no endereço IP público, deve ter todos os certificados HTTPS no servidor.
* Para que isso funcione, um único componente (programa) em execução no servidor, ouvindo no endereço IP público, deve ter todos os certificados HTTPS no servidor.
* Depois de obter uma conexão segura, o protocolo de comunicação ainda é HTTP.
* Depois de obter uma conexão segura, o protocolo de comunicação ainda é HTTP.
* Os conteúdos são criptografados, embora sejam enviados com o protocolo HTTP.
* Os conteúdos são criptografados, embora sejam enviados com o protocolo HTTP.
É uma prática comum ter um programa/servidor HTTP em execução no servidor (máquina, host, etc.) e gerenciar todas as partes HTTPS: recebendo as requisições HTTPS encriptadas, enviando as solicitações HTTP descriptografadas para o aplicativo HTTP real em execução no mesmo servidor (a aplicação FastAPI, neste caso), pegar a resposta HTTP do aplicativo, criptografá-la usando o certificado HTTPS apropriado e enviá-la de volta ao cliente usando HTTPS. Este servidor é frequentemente chamado de <ahref="https://en.wikipedia.org/wiki/TLS_termination_proxy"class="external-link"target="_blank">Proxy de Terminação TLS</a>.
É uma prática comum ter um programa/servidor HTTP em execução no servidor (máquina, host, etc.) e gerenciar todas as partes HTTPS: recebendo as requisições HTTPS encriptadas, enviando as solicitações HTTP descriptografadas para o aplicativo HTTP real em execução no mesmo servidor (a aplicação FastAPI, neste caso), pegar a resposta HTTP do aplicativo, criptografá-la usando o certificado HTTPS apropriado e enviá-la de volta ao cliente usando HTTPS. Este servidor é frequentemente chamado de [Proxy de Terminação TLS](https://en.wikipedia.org/wiki/TLS_termination_proxy).
Algumas das opções que você pode usar como Proxy de Terminação TLS são:
Algumas das opções que você pode usar como Proxy de Terminação TLS são:
@ -49,7 +49,7 @@ Antes de Let's Encrypt, esses certificados HTTPS eram vendidos por terceiros con
O processo de aquisição de um desses certificados costumava ser complicado, exigia bastante papelada e os certificados eram bastante caros.
O processo de aquisição de um desses certificados costumava ser complicado, exigia bastante papelada e os certificados eram bastante caros.
Mas então o <ahref="https://letsencrypt.org/"class="external-link"target="_blank">Let's Encrypt</a> foi criado.
Mas então o [Let's Encrypt](https://letsencrypt.org/) foi criado.
Ele é um projeto da Linux Foundation que fornece certificados HTTPS gratuitamente. De forma automatizada. Esses certificados usam toda a segurança criptográfica padrão e têm vida curta (cerca de 3 meses), então a segurança é, na verdade, melhor por causa do seu lifespan reduzido.
Ele é um projeto da Linux Foundation que fornece certificados HTTPS gratuitamente. De forma automatizada. Esses certificados usam toda a segurança criptográfica padrão e têm vida curta (cerca de 3 meses), então a segurança é, na verdade, melhor por causa do seu lifespan reduzido.
@ -200,9 +200,9 @@ Esse proxy normalmente define alguns cabeçalhos HTTP dinamicamente antes de tra
@ -218,7 +218,7 @@ Isso seria útil, por exemplo, para lidar corretamente com redirecionamentos.
/// tip | Dica
/// tip | Dica
Você pode saber mais sobre isso na documentação em [Atrás de um Proxy - Habilitar cabeçalhos encaminhados pelo proxy](../advanced/behind-a-proxy.md#enable-proxy-forwarded-headers){.internal-link target=_blank}
Você pode saber mais sobre isso na documentação em [Atrás de um Proxy - Habilitar cabeçalhos encaminhados pelo proxy](../advanced/behind-a-proxy.md#enable-proxy-forwarded-headers)
@ -16,7 +16,7 @@ Há várias maneiras de fazer isso, dependendo do seu caso de uso específico e
Você pode **implantar um servidor** por conta própria usando uma combinação de ferramentas, pode usar um **serviço em nuvem** que faça parte do trabalho por você, entre outras opções.
Você pode **implantar um servidor** por conta própria usando uma combinação de ferramentas, pode usar um **serviço em nuvem** que faça parte do trabalho por você, entre outras opções.
Por exemplo, nós, a equipe por trás do FastAPI, criamos <ahref="https://fastapicloud.com"class="external-link"target="_blank">**FastAPI Cloud**</a>, para tornar a implantação de aplicações FastAPI na nuvem o mais simples possível, com a mesma experiência de desenvolvimento de trabalhar com o FastAPI.
Por exemplo, nós, a equipe por trás do FastAPI, criamos [**FastAPI Cloud**](https://fastapicloud.com), para tornar a implantação de aplicações FastAPI na nuvem o mais simples possível, com a mesma experiência de desenvolvimento de trabalhar com o FastAPI.
Vou mostrar alguns dos principais conceitos que você provavelmente deve ter em mente ao implantar uma aplicação **FastAPI** (embora a maior parte se aplique a qualquer outro tipo de aplicação web).
Vou mostrar alguns dos principais conceitos que você provavelmente deve ter em mente ao implantar uma aplicação **FastAPI** (embora a maior parte se aplique a qualquer outro tipo de aplicação web).
@ -52,11 +52,11 @@ A principal coisa que você precisa para executar uma aplicação **FastAPI** (o
Existem diversas alternativas, incluindo:
Existem diversas alternativas, incluindo:
* <ahref="https://www.uvicorn.dev/"class="external-link"target="_blank">Uvicorn</a>: um servidor ASGI de alta performance.
* [Uvicorn](https://www.uvicorn.dev/): um servidor ASGI de alta performance.
* <ahref="https://hypercorn.readthedocs.io/"class="external-link"target="_blank">Hypercorn</a>: um servidor ASGI compatível com HTTP/2, Trio e outros recursos.
* [Hypercorn](https://hypercorn.readthedocs.io/): um servidor ASGI compatível com HTTP/2, Trio e outros recursos.
* <ahref="https://github.com/django/daphne"class="external-link"target="_blank">Daphne</a>: servidor ASGI construído para Django Channels.
* [Daphne](https://github.com/django/daphne): servidor ASGI construído para Django Channels.
* <ahref="https://github.com/emmett-framework/granian"class="external-link"target="_blank">Granian</a>: um servidor HTTP Rust para aplicações Python.
* [Granian](https://github.com/emmett-framework/granian): um servidor HTTP Rust para aplicações Python.
* <ahref="https://unit.nginx.org/howto/fastapi/"class="external-link"target="_blank">NGINX Unit</a>: NGINX Unit é um runtime de aplicação web leve e versátil.
* [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 }
## Máquina Servidora e Programa Servidor { #server-machine-and-server-program }
@ -74,7 +74,7 @@ Quando você instala o FastAPI, ele vem com um servidor de produção, o Uvicorn
Mas você também pode instalar um servidor ASGI manualmente.
Mas você também pode instalar um servidor ASGI manualmente.
Certifique-se de criar um [ambiente virtual](../virtual-environments.md){.internal-link target=_blank}, ativá-lo e, em seguida, você pode instalar a aplicação do servidor.
Certifique-se de criar um [ambiente virtual](../virtual-environments.md), ativá-lo e, em seguida, você pode instalar a aplicação do servidor.
@ -13,13 +13,13 @@ Até este ponto, com todos os tutoriais nos documentos, você provavelmente esta
Ao implantar aplicativos, você provavelmente desejará ter alguma **replicação de processos** para aproveitar **vários núcleos** e poder lidar com mais solicitações.
Ao implantar aplicativos, você provavelmente desejará ter alguma **replicação de processos** para aproveitar **vários núcleos** e poder lidar com mais solicitações.
Como você viu no capítulo anterior sobre [Conceitos de implantação](concepts.md){.internal-link target=_blank}, há várias estratégias que você pode usar.
Como você viu no capítulo anterior sobre [Conceitos de implantação](concepts.md), há várias estratégias que você pode usar.
Aqui mostrarei como usar o **Uvicorn** com **processos de trabalho** usando o comando `fastapi` ou o comando `uvicorn` diretamente.
Aqui mostrarei como usar o **Uvicorn** com **processos de trabalho** usando o comando `fastapi` ou o comando `uvicorn` diretamente.
/// info | Informação
/// info | Informação
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){.internal-link target=_blank}.
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).
Em particular, ao executar no **Kubernetes** você provavelmente **não** vai querer usar vários trabalhadores e, em vez disso, executar **um único processo Uvicorn por contêiner**, mas falarei sobre isso mais adiante neste capítulo.
Em particular, ao executar no **Kubernetes** você provavelmente **não** vai querer usar vários trabalhadores e, em vez disso, executar **um único processo Uvicorn por contêiner**, mas falarei sobre isso mais adiante neste capítulo.
<spanstyle="background-color:#007166"><fontcolor="#D3D7CF"> INFO </font></span> Started parent process <b>[</b><fontcolor="#34E2E2"><b>27365</b></font><b>]</b>
<spanstyle="background-color:#007166"><fontcolor="#D3D7CF"> INFO </font></span> Started parent process <b>[</b><fontcolor="#34E2E2"><b>27365</b></font><b>]</b>
<spanstyle="background-color:#007166"><fontcolor="#D3D7CF"> INFO </font></span> Started server process <b>[</b><fontcolor="#34E2E2"><b>27368</b></font><b>]</b>
<spanstyle="background-color:#007166"><fontcolor="#D3D7CF"> INFO </font></span> Started server process <b>[</b><fontcolor="#34E2E2"><b>27368</b></font><b>]</b>
<spanstyle="background-color:#007166"><fontcolor="#D3D7CF"> INFO </font></span> Started server process <b>[</b><fontcolor="#34E2E2"><b>27369</b></font><b>]</b>
<spanstyle="background-color:#007166"><fontcolor="#D3D7CF"> INFO </font></span> Started server process <b>[</b><fontcolor="#34E2E2"><b>27369</b></font><b>]</b>
<spanstyle="background-color:#007166"><fontcolor="#D3D7CF"> INFO </font></span> Started server process <b>[</b><fontcolor="#34E2E2"><b>27370</b></font><b>]</b>
<spanstyle="background-color="#007166"><fontcolor="#D3D7CF"> INFO </font></span> Started server process <b>[</b><fontcolor="#34E2E2"><b>27370</b></font><b>]</b>
<spanstyle="background-color:#007166"><fontcolor="#D3D7CF"> INFO </font></span> Started server process <b>[</b><fontcolor="#34E2E2"><b>27367</b></font><b>]</b>
<spanstyle="background-color="#007166"><fontcolor="#D3D7CF"> INFO </font></span> Started server process <b>[</b><fontcolor="#34E2E2"><b>27367</b></font><b>]</b>
<spanstyle="background-color="#007166"><fontcolor="#D3D7CF"> INFO </font></span> Waiting for application startup.
<spanstyle="background-color:#007166"><fontcolor="#D3D7CF"> INFO </font></span> Waiting for application startup.
<spanstyle="background-color:#007166"><fontcolor="#D3D7CF"> INFO </font></span> Waiting for application startup.
<spanstyle="background-color="#007166"><fontcolor="#D3D7CF"> INFO </font></span> Waiting for application startup.
<spanstyle="background-color:#007166"><fontcolor="#D3D7CF"> INFO </font></span> Waiting for application startup.
<spanstyle="background-color:#007166"><fontcolor="#D3D7CF"> INFO </font></span> Waiting for application startup.
<spanstyle="background-color:#007166"><fontcolor="#D3D7CF"> INFO </font></span> Waiting for application startup.
<spanstyle="background-color="#007166"><fontcolor="#D3D7CF"> INFO </font></span> Application startup complete.
<spanstyle="background-color:#007166"><fontcolor="#D3D7CF"> INFO </font></span> Waiting for application startup.
<spanstyle="background-color="#007166"><fontcolor="#D3D7CF"> INFO </font></span> Application startup complete.
<spanstyle="background-color:#007166"><fontcolor="#D3D7CF"> INFO </font></span> Application startup complete.
<spanstyle="background-color:#007166"><fontcolor="#D3D7CF"> INFO </font></span> Application startup complete.
<spanstyle="background-color:#007166"><fontcolor="#D3D7CF"> INFO </font></span> Application startup complete.
<spanstyle="background-color:#007166"><fontcolor="#D3D7CF"> INFO </font></span> Application startup complete.
<spanstyle="background-color:#007166"><fontcolor="#D3D7CF"> INFO </font></span> Application startup complete.
<spanstyle="background-color:#007166"><fontcolor="#D3D7CF"> INFO </font></span> Application startup complete.
```
```
@ -126,7 +126,7 @@ Da lista de conceitos de implantação acima, o uso de trabalhadores ajudaria pr
## Contêineres e Docker { #containers-and-docker }
## Contêineres e Docker { #containers-and-docker }
No próximo capítulo sobre [FastAPI em contêineres - Docker](docker.md){.internal-link target=_blank}, explicarei algumas estratégias que você pode usar para lidar com os outros **conceitos de implantação**.
No próximo capítulo sobre [FastAPI em contêineres - Docker](docker.md), explicarei algumas estratégias que você pode usar para lidar com os outros **conceitos de implantação**.
Vou mostrar como **construir sua própria imagem do zero** para executar um único processo Uvicorn. É um processo simples e provavelmente é o que você gostaria de fazer ao usar um sistema de gerenciamento de contêineres distribuídos como o **Kubernetes**.
Vou mostrar como **construir sua própria imagem do zero** para executar um único processo Uvicorn. É um processo simples e provavelmente é o que você gostaria de fazer ao usar um sistema de gerenciamento de contêineres distribuídos como o **Kubernetes**.
Novas funcionalidades são adicionadas com frequência, bugs são corrigidos regularmente e o código continua melhorando continuamente.
Novas funcionalidades são adicionadas com frequência, bugs são corrigidos regularmente e o código continua melhorando continuamente.
É por isso que as versões atuais ainda são `0.x.x`, isso reflete que cada versão pode potencialmente ter mudanças significativas. Isso segue as convenções de <ahref="https://semver.org/"class="external-link"target="_blank">Versionamento Semântico</a>.
É por isso que as versões atuais ainda são `0.x.x`, isso reflete que cada versão pode potencialmente ter mudanças significativas. Isso segue as convenções de [Versionamento Semântico](https://semver.org/).
Você pode criar aplicações de produção com **FastAPI** agora mesmo (e provavelmente já vem fazendo isso há algum tempo), apenas certifique-se de usar uma versão que funcione corretamente com o resto do seu código.
Você pode criar aplicações de produção com **FastAPI** agora mesmo (e provavelmente já vem fazendo isso há algum tempo), apenas certifique-se de usar uma versão que funcione corretamente com o resto do seu código.
@ -34,7 +34,7 @@ Se você usa qualquer outra ferramenta para gerenciar suas instalações, como `
## Versões disponíveis { #available-versions }
## Versões disponíveis { #available-versions }
Você pode ver as versões disponíveis (por exemplo, para verificar qual é a mais recente) nas [Release Notes](../release-notes.md){.internal-link target=_blank}.
Você pode ver as versões disponíveis (por exemplo, para verificar qual é a mais recente) nas [Release Notes](../release-notes.md).
## Sobre versões { #about-versions }
## Sobre versões { #about-versions }
@ -66,7 +66,7 @@ O "MINOR" é o número do meio, por exemplo, em `0.2.3`, a versão MINOR é `2`.
Você deveria adicionar testes para a sua aplicação.
Você deveria adicionar testes para a sua aplicação.
Com **FastAPI** isso é muito fácil (graças ao Starlette), veja a documentação: [Testes](../tutorial/testing.md){.internal-link target=_blank}
Com **FastAPI** isso é muito fácil (graças ao Starlette), veja a documentação: [Testes](../tutorial/testing.md)
Depois que você tiver testes, você pode atualizar a sua versão do **FastAPI** para uma mais recente e se certificar de que todo o seu código está funcionando corretamente executando seus testes.
Depois que você tiver testes, você pode atualizar a sua versão do **FastAPI** para uma mais recente e se certificar de que todo o seu código está funcionando corretamente executando seus testes.
Antes da versão `0.122.0` do FastAPI, quando os utilitários de segurança integrados retornavam um erro ao cliente após uma falha na autenticação, eles usavam o código de status HTTP `403 Forbidden`.
Antes da versão `0.122.0` do FastAPI, quando os utilitários de segurança integrados retornavam um erro ao cliente após uma falha na autenticação, eles usavam o código de status HTTP `403 Forbidden`.
A partir da versão `0.122.0` do FastAPI, eles usam o código de status HTTP `401 Unauthorized`, mais apropriado, e retornam um cabeçalho `WWW-Authenticate` adequado na response, seguindo as especificações HTTP, <ahref="https://datatracker.ietf.org/doc/html/rfc7235#section-3.1"class="external-link"target="_blank">RFC 7235</a>, <ahref="https://datatracker.ietf.org/doc/html/rfc9110#name-401-unauthorized"class="external-link"target="_blank">RFC 9110</a>.
A partir da versão `0.122.0` do FastAPI, eles usam o código de status HTTP `401 Unauthorized`, mais apropriado, e retornam um cabeçalho `WWW-Authenticate` adequado na response, seguindo as especificações HTTP, [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235#section-3.1), [RFC 9110](https://datatracker.ietf.org/doc/html/rfc9110#name-401-unauthorized).
Mas, se por algum motivo seus clientes dependem do comportamento antigo, você pode voltar a ele sobrescrevendo o método `make_not_authenticated_error` nas suas classes de segurança.
Mas, se por algum motivo seus clientes dependem do comportamento antigo, você pode voltar a ele sobrescrevendo o método `make_not_authenticated_error` nas suas classes de segurança.
@ -10,11 +10,11 @@ Isso não adiciona nenhuma segurança extra à sua API; as *operações de rota*
Se houver uma falha de segurança no seu código, ela ainda existirá.
Se houver uma falha de segurança no seu código, ela ainda existirá.
Ocultar a documentação apenas torna mais difícil entender como interagir com sua API e pode dificultar sua depuração na produção. Pode ser considerado simplesmente uma forma de <ahref="https://en.wikipedia.org/wiki/Security_through_obscurity"class="external-link"target="_blank">Segurança através da obscuridade</a>.
Ocultar a documentação apenas torna mais difícil entender como interagir com sua API e pode dificultar sua depuração na produção. Pode ser considerado simplesmente uma forma de [Segurança através da obscuridade](https://en.wikipedia.org/wiki/Security_through_obscurity).
Se você quiser proteger sua API, há várias coisas melhores que você pode fazer, por exemplo:
Se você quiser proteger sua API, há várias coisas melhores que você pode fazer, por exemplo:
* Certifique-se de ter modelos Pydantic bem definidos para seus corpos de solicitação e respostas.
* Certifique-se de ter modelos Pydantic bem definidos para seus corpos de request e respostas.
* Configure quaisquer permissões e funções necessárias usando dependências.
* Configure quaisquer permissões e funções necessárias usando dependências.
* Nunca armazene senhas em texto simples, apenas hashes de senha.
* Nunca armazene senhas em texto simples, apenas hashes de senha.
* Implemente e use ferramentas criptográficas bem conhecidas, como pwdlib e tokens JWT, etc.
* Implemente e use ferramentas criptográficas bem conhecidas, como pwdlib e tokens JWT, etc.
# Configure a UI do Swagger { #configure-swagger-ui }
# Configure a UI do Swagger { #configure-swagger-ui }
Você pode configurar alguns <ahref="https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/"class="external-link"target="_blank">parâmetros extras da UI do Swagger</a>.
Você pode configurar alguns [parâmetros extras da UI do Swagger](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/).
Para configurá-los, passe o argumento `swagger_ui_parameters` ao criar o objeto da aplicação `FastAPI()` ou para a função `get_swagger_ui_html()`.
Para configurá-los, passe o argumento `swagger_ui_parameters` ao criar o objeto da aplicação `FastAPI()` ou para a função `get_swagger_ui_html()`.
@ -50,7 +50,7 @@ Por exemplo, para desabilitar `deepLinking` você pode passar essas configuraç
## Outros parâmetros da UI do Swagger { #other-swagger-ui-parameters }
## Outros parâmetros da UI do Swagger { #other-swagger-ui-parameters }
Para ver todas as outras configurações possíveis que você pode usar, leia a <ahref="https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/"class="external-link"target="_blank">documentação oficial dos parâmetros da UI do Swagger</a>.
Para ver todas as outras configurações possíveis que você pode usar, leia a [documentação oficial dos parâmetros da UI do Swagger](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/).
## Configurações somente JavaScript { #javascript-only-settings }
## Configurações somente JavaScript { #javascript-only-settings }
@ -54,7 +54,7 @@ Agora, para poder testar se tudo funciona, crie uma *operação de rota*:
### Teste { #test-it }
### Teste { #test-it }
Agora, você deve ser capaz de ir para a documentação em <ahref="http://127.0.0.1:8000/docs"class="external-link"target="_blank">http://127.0.0.1:8000/docs</a>, e recarregar a página, ela carregará esses recursos do novo CDN.
Agora, você deve ser capaz de ir para a documentação em [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs), e recarregar a página, ela carregará esses recursos do novo CDN.
## Hospedagem Própria de JavaScript e CSS para a documentação { #self-hosting-javascript-and-css-for-docs }
## Hospedagem Própria de JavaScript e CSS para a documentação { #self-hosting-javascript-and-css-for-docs }
@ -89,16 +89,16 @@ Sua nova estrutura de arquivos poderia se parecer com isso:
Baixe os arquivos estáticos necessários para a documentação e coloque-os no diretório `static/`.
Baixe os arquivos estáticos necessários para a documentação e coloque-os no diretório `static/`.
Você provavelmente pode clicar com o botão direito em cada link e selecionar uma opção semelhante a `Salvar link como...`.
Você provavelmente pode clicar com o botão direito em cada link e selecionar uma opção semelhante a "Salvar link como...".
Depois disso, sua estrutura de arquivos deve se parecer com:
Depois disso, sua estrutura de arquivos deve se parecer com:
@ -122,9 +122,9 @@ Depois disso, sua estrutura de arquivos deve se parecer com:
### Teste os arquivos estáticos { #test-the-static-files }
### Teste os arquivos estáticos { #test-the-static-files }
Inicialize seu aplicativo e vá para <ahref="http://127.0.0.1:8000/static/redoc.standalone.js"class="external-link"target="_blank">http://127.0.0.1:8000/static/redoc.standalone.js</a>.
Inicialize seu aplicativo e vá para [http://127.0.0.1:8000/static/redoc.standalone.js](http://127.0.0.1:8000/static/redoc.standalone.js).
Você deverá ver um arquivo JavaScript muito longo para o **ReDoc**.
Você deverá ser ver um arquivo JavaScript muito longo para o **ReDoc**.
Esse arquivo pode começar com algo como:
Esse arquivo pode começar com algo como:
@ -180,6 +180,6 @@ Agora, para poder testar se tudo funciona, crie uma *operação de rota*:
### Teste a UI de Arquivos Estáticos { #test-static-files-ui }
### Teste a UI de Arquivos Estáticos { #test-static-files-ui }
Agora, você deve ser capaz de desconectar o WiFi, ir para a documentação em <ahref="http://127.0.0.1:8000/docs"class="external-link"target="_blank">http://127.0.0.1:8000/docs</a>, e recarregar a página.
Agora, você deve ser capaz de desconectar o WiFi, ir para a documentação em [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs), e recarregar a página.
E mesmo sem Internet, você será capaz de ver a documentação da sua API e interagir com ela.
E mesmo sem Internet, você será capaz de ver a documentação da sua API e interagir com ela.
@ -18,7 +18,7 @@ Se você for um iniciante em **FastAPI** você deve considerar pular essa seçã
Alguns casos de uso incluem:
Alguns casos de uso incluem:
* Converter requisições não-JSON para JSON (por exemplo, <ahref="https://msgpack.org/index.html"class="external-link"target="_blank">`msgpack`</a>).
* Converter requisições não-JSON para JSON (por exemplo, [`msgpack`](https://msgpack.org/index.html)).
* Descomprimir corpos de requisição comprimidos com gzip.
* Descomprimir corpos de requisição comprimidos com gzip.
* Registrar automaticamente todos os corpos de requisição.
* Registrar automaticamente todos os corpos de requisição.
@ -32,7 +32,7 @@ E uma subclasse de `APIRoute` para usar essa classe de requisição personalizad
/// tip | Dica
/// tip | Dica
Isso é um exemplo de brincadeira para demonstrar como funciona, se você precisar de suporte para Gzip, você pode usar o [`GzipMiddleware`](../advanced/middleware.md#gzipmiddleware){.internal-link target=_blank} fornecido.
Isso é um exemplo de brincadeira para demonstrar como funciona, se você precisar de suporte para Gzip, você pode usar o [`GzipMiddleware`](../advanced/middleware.md#gzipmiddleware) fornecido.
///
///
@ -66,7 +66,7 @@ O dicionário `scope` e a função `receive` são ambos parte da especificação
E essas duas coisas, `scope` e `receive`, são o que é necessário para criar uma nova instância de `Request`.
E essas duas coisas, `scope` e `receive`, são o que é necessário para criar uma nova instância de `Request`.
Para aprender mais sobre o `Request` confira a <ahref="https://www.starlette.dev/requests/"class="external-link"target="_blank">documentação do Starlette sobre Requests</a>.
Para aprender mais sobre o `Request` confira a [documentação do Starlette sobre Requests](https://www.starlette.dev/requests/).
///
///
@ -82,7 +82,7 @@ Mas por causa das nossas mudanças em `GzipRequest.body`, o corpo da requisiçã
/// tip | Dica
/// tip | Dica
Para resolver esse mesmo problema, é provavelmente muito mais fácil usar o `body` em um manipulador personalizado para `RequestValidationError` ([Tratando Erros](../tutorial/handling-errors.md#use-the-requestvalidationerror-body){.internal-link target=_blank}).
Para resolver esse mesmo problema, é provavelmente muito mais fácil usar o `body` em um manipulador personalizado para `RequestValidationError` ([Tratando Erros](../tutorial/handling-errors.md#use-the-requestvalidationerror-body)).
Mas esse exemplo ainda é valido e mostra como interagir com os componentes internos.
Mas esse exemplo ainda é valido e mostra como interagir com os componentes internos.
@ -37,7 +37,7 @@ O parâmetro `summary` está disponível no OpenAPI 3.1.0 e superior, suportado
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.
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 <ahref="https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo"class="external-link"target="_blank">Extensão OpenAPI do ReDoc para incluir um logo personalizado</a>.
Por exemplo, vamos adicionar [Extensão OpenAPI do ReDoc para incluir um logo personalizado](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo).
### **FastAPI** Normal { #normal-fastapi }
### **FastAPI** Normal { #normal-fastapi }
@ -75,6 +75,6 @@ Agora, você pode substituir o método `.openapi()` pela sua nova função.
### Verificar { #check-it }
### Verificar { #check-it }
Uma vez que você acessar <ahref="http://127.0.0.1:8000/redoc"class="external-link"target="_blank">http://127.0.0.1:8000/redoc</a>, verá que está usando seu logo personalizado (neste exemplo, o logo do **FastAPI**):
Uma vez que você acessar [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc), verá que está usando seu logo personalizado (neste exemplo, o logo do **FastAPI**):
# Geral - Como Fazer - Receitas { #general-how-to-recipes }
# Geral - Como Fazer - Receitas { #general-how-to-recipes }
Aqui estão vários links para outros locais na documentação, para perguntas gerais ou frequentes
Aqui estão vários links para outros locais na documentação, para perguntas gerais ou frequentes.
## Filtro de dados- Segurança { #filter-data-security }
## Filtro de dados- Segurança { #filter-data-security }
Para assegurar que você não vai retornar mais dados do que deveria, leia a seção [Tutorial - Modelo de Resposta - Tipo de Retorno](../tutorial/response-model.md){.internal-link target=_blank}.
Para assegurar que você não vai retornar mais dados do que deveria, leia a documentação de [Tutorial - Modelo de Resposta - Tipo de Retorno](../tutorial/response-model.md).
## Otimizar Desempenho da Resposta - Modelo de Resposta - Tipo de Retorno { #optimize-response-performance-response-model-return-type }
Para otimizar o desempenho ao retornar dados JSON, use um tipo de retorno ou modelo de resposta; assim, o Pydantic fará a serialização para JSON no lado do Rust, sem passar pelo Python. Leia mais na documentação de [Tutorial - Modelo de Resposta - Tipo de Retorno](../tutorial/response-model.md).
## Tags de Documentação - OpenAPI { #documentation-tags-openapi }
## Tags de Documentação - OpenAPI { #documentation-tags-openapi }
Para adicionar tags às suas *operações de rota* e agrupá-las na UI da documentação, leia a seção [Tutorial - Configurações da Operação de Rota - Tags](../tutorial/path-operation-configuration.md#tags){.internal-link target=_blank}.
Para adicionar tags às suas *operações de rota* e agrupá-las na UI da documentação, leia a documentação de [Tutorial - Configurações da Operação de Rota - Tags](../tutorial/path-operation-configuration.md#tags).
## Resumo e Descrição da documentação - OpenAPI { #documentation-summary-and-description-openapi }
## Resumo e Descrição da documentação - OpenAPI { #documentation-summary-and-description-openapi }
Para adicionar um resumo e uma descrição às suas *operações de rota* e exibi-los na UI da documentação, leia a seção [Tutorial - Configurações da Operação de Rota - Resumo e Descrição](../tutorial/path-operation-configuration.md#summary-and-description){.internal-link target=_blank}.
Para adicionar um resumo e uma descrição às suas *operações de rota* e exibi-los na UI da documentação, leia a documentação de [Tutorial - Configurações da Operação de Rota - Resumo e Descrição](../tutorial/path-operation-configuration.md#summary-and-description).
## Documentação das Descrições de Resposta - OpenAPI { #documentation-response-description-openapi }
Para definir a descrição de uma resposta exibida na interface da documentação, leia a seção [Tutorial - Configurações da Operação de Rota - Descrição da Resposta](../tutorial/path-operation-configuration.md#response-description){.internal-link target=_blank}.
Para definir a descrição de uma resposta exibida na interface da documentação, leia a documentação de [Tutorial - Configurações da Operação de Rota - Descrição da Resposta](../tutorial/path-operation-configuration.md#response-description).
## Documentação para Depreciar uma *Operação de Rota* - OpenAPI { #documentation-deprecate-a-path-operation-openapi }
## Documentação - Descontinuar uma *Operação de Rota* - OpenAPI { #documentation-deprecate-a-path-operation-openapi }
Para depreciar uma *operação de rota* e exibi-la na interface da documentação, leia a seção [Tutorial - Configurações da Operação de Rota - Depreciação](../tutorial/path-operation-configuration.md#deprecate-a-path-operation){.internal-link target=_blank}.
Para descontinuar uma *operação de rota* e exibi-la na UI da documentação, leia a documentação de [Tutorial - Configurações da Operação de Rota - Descontinuação](../tutorial/path-operation-configuration.md#deprecate-a-path-operation).
## Converter qualquer dado para compatível com JSON { #convert-any-data-to-json-compatible }
## Converter qualquer dado para compatível com JSON { #convert-any-data-to-json-compatible }
Para converter qualquer dado para um formato compatível com JSON, leia a seção [Tutorial - Codificador Compatível com JSON](../tutorial/encoder.md){.internal-link target=_blank}.
Para converter qualquer dado para um formato compatível com JSON, leia a documentação de [Tutorial - Codificador Compatível com JSON](../tutorial/encoder.md).
Para adicionar metadados ao seu esquema OpenAPI, incluindo licença, versão, contato, etc, leia a seção [Tutorial - Metadados e URLs da Documentação](../tutorial/metadata.md){.internal-link target=_blank}.
Para adicionar metadados ao seu esquema OpenAPI, incluindo licença, versão, contato, etc, leia a documentação de [Tutorial - Metadados e URLs da Documentação](../tutorial/metadata.md).
## OpenAPI com URL customizada { #openapi-custom-url }
## OpenAPI com URL customizada { #openapi-custom-url }
Para customizar a URL do OpenAPI (ou removê-la), leia a seção [Tutorial - Metadados e URLs da Documentação](../tutorial/metadata.md#openapi-url){.internal-link target=_blank}.
Para customizar a URL do OpenAPI (ou removê-la), leia a documentação de [Tutorial - Metadados e URLs da Documentação](../tutorial/metadata.md#openapi-url).
## URLs de documentação do OpenAPI { #openapi-docs-urls }
## URLs de documentação do OpenAPI { #openapi-docs-urls }
Para alterar as URLs usadas para as interfaces de usuário da documentação gerada automaticamente, leia a seção [Tutorial - Metadados e URLs da Documentação](../tutorial/metadata.md#docs-urls){.internal-link target=_blank}.
Para alterar as URLs usadas para as interfaces de usuário da documentação gerada automaticamente, leia a documentação de [Tutorial - Metadados e URLs da Documentação](../tutorial/metadata.md#docs-urls).
* Com <ahref="https://github.com/ciscorn/starlette-graphene3"class="external-link"target="_blank">starlette-graphene3</a>
* Com [starlette-graphene3](https://github.com/ciscorn/starlette-graphene3)
## GraphQL com Strawberry { #graphql-with-strawberry }
## GraphQL com Strawberry { #graphql-with-strawberry }
Se você precisar ou quiser trabalhar com **GraphQL**, <ahref="https://strawberry.rocks/"class="external-link"target="_blank">**Strawberry**</a> é a biblioteca **recomendada** pois tem o design mais próximo ao design do **FastAPI**, ela é toda baseada em **anotações de tipo**.
Se você precisar ou quiser trabalhar com **GraphQL**, [**Strawberry**](https://strawberry.rocks/) é a biblioteca **recomendada** pois tem o design mais próximo ao design do **FastAPI**, ela é toda baseada em **anotações de tipo**.
Dependendo do seu caso de uso, você pode preferir usar uma biblioteca diferente, mas se você me perguntasse, eu provavelmente sugeriria que você experimentasse o **Strawberry**.
Dependendo do seu caso de uso, você pode preferir usar uma biblioteca diferente, mas se você me perguntasse, eu provavelmente sugeriria que você experimentasse o **Strawberry**.
@ -37,24 +37,24 @@ Aqui está uma pequena prévia de como você poderia integrar Strawberry com Fas
Você pode aprender mais sobre Strawberry na <ahref="https://strawberry.rocks/"class="external-link"target="_blank">documentação do Strawberry</a>.
Você pode aprender mais sobre Strawberry na [documentação do Strawberry](https://strawberry.rocks/).
E também na documentação sobre <ahref="https://strawberry.rocks/docs/integrations/fastapi"class="external-link"target="_blank">Strawberry com FastAPI</a>.
E também na documentação sobre [Strawberry com FastAPI](https://strawberry.rocks/docs/integrations/fastapi).
## Antigo `GraphQLApp` do Starlette { #older-graphqlapp-from-starlette }
## Antigo `GraphQLApp` do Starlette { #older-graphqlapp-from-starlette }
Versões anteriores do Starlette incluiam uma classe `GraphQLApp` para integrar com <ahref="https://graphene-python.org/"class="external-link"target="_blank">Graphene</a>.
Versões anteriores do Starlette incluiam uma classe `GraphQLApp` para integrar com [Graphene](https://graphene-python.org/).
Ela foi descontinuada do Starlette, mas se você tem código que a utilizava, você pode facilmente **migrar** para <ahref="https://github.com/ciscorn/starlette-graphene3"class="external-link"target="_blank">starlette-graphene3</a>, que cobre o mesmo caso de uso e tem uma **interface quase idêntica**.
Ela foi descontinuada do Starlette, mas se você tem código que a utilizava, você pode facilmente **migrar** para [starlette-graphene3](https://github.com/ciscorn/starlette-graphene3), que cobre o mesmo caso de uso e tem uma **interface quase idêntica**.
/// tip | Dica
/// tip | Dica
Se você precisa de GraphQL, eu ainda recomendaria que você desse uma olhada no <ahref="https://strawberry.rocks/"class="external-link"target="_blank">Strawberry</a>, pois ele é baseado em anotações de tipo em vez de classes e tipos personalizados.
Se você precisa de GraphQL, eu ainda recomendaria que você desse uma olhada no [Strawberry](https://strawberry.rocks/), pois ele é baseado em anotações de tipo em vez de classes e tipos personalizados.
///
///
## Saiba Mais { #learn-more }
## Saiba Mais { #learn-more }
Você pode aprender mais sobre **GraphQL** na <ahref="https://graphql.org/"class="external-link"target="_blank">documentação oficial do GraphQL</a>.
Você pode aprender mais sobre **GraphQL** na [documentação oficial do GraphQL](https://graphql.org/).
Você também pode ler mais sobre cada uma das bibliotecas descritas acima em seus links.
Você também pode ler mais sobre cada uma das bibliotecas descritas acima em seus links.
@ -8,6 +8,6 @@ Se algo parecer interessante e útil para o seu projeto, vá em frente e dê uma
/// tip | Dica
/// tip | Dica
Se você deseja **aprender FastAPI** de forma estruturada (recomendado), leia capítulo por capítulo [Tutorial - Guia de Usuário](../tutorial/index.md){.internal-link target=_blank} em vez disso.
Se você deseja **aprender FastAPI** de forma estruturada (recomendado), leia capítulo por capítulo [Tutorial - Guia de Usuário](../tutorial/index.md) em vez disso.
@ -22,7 +22,7 @@ Se você tem uma aplicação FastAPI antiga com Pydantic v1, aqui vou mostrar co
## Guia oficial { #official-guide }
## Guia oficial { #official-guide }
O Pydantic tem um <ahref="https://docs.pydantic.dev/latest/migration/"class="external-link"target="_blank">Guia de Migração</a> oficial do v1 para o v2.
O Pydantic tem um [Guia de Migração](https://docs.pydantic.dev/latest/migration/) oficial do v1 para o v2.
Ele também inclui o que mudou, como as validações agora são mais corretas e rigorosas, possíveis ressalvas, etc.
Ele também inclui o que mudou, como as validações agora são mais corretas e rigorosas, possíveis ressalvas, etc.
@ -30,7 +30,7 @@ Você pode lê-lo para entender melhor o que mudou.
## Testes { #tests }
## Testes { #tests }
Garanta que você tenha [testes](../tutorial/testing.md){.internal-link target=_blank} para sua aplicação e que os execute na integração contínua (CI).
Garanta que você tenha [testes](../tutorial/testing.md) para sua aplicação e que os execute na integração contínua (CI).
Assim, você pode fazer a atualização e garantir que tudo continua funcionando como esperado.
Assim, você pode fazer a atualização e garantir que tudo continua funcionando como esperado.
@ -38,7 +38,7 @@ Assim, você pode fazer a atualização e garantir que tudo continua funcionando
Em muitos casos, quando você usa modelos Pydantic regulares sem personalizações, será possível automatizar a maior parte do processo de migração do Pydantic v1 para o Pydantic v2.
Em muitos casos, quando você usa modelos Pydantic regulares sem personalizações, será possível automatizar a maior parte do processo de migração do Pydantic v1 para o Pydantic v2.
Você pode usar o <ahref="https://github.com/pydantic/bump-pydantic"class="external-link"target="_blank">`bump-pydantic`</a> da própria equipe do Pydantic.
Você pode usar [`bump-pydantic`](https://github.com/pydantic/bump-pydantic) da própria equipe do Pydantic.
Essa ferramenta ajuda a alterar automaticamente a maior parte do código que precisa ser modificado.
Essa ferramenta ajuda a alterar automaticamente a maior parte do código que precisa ser modificado.
# Testando a Base de Dados { #testing-a-database }
# Testando a Base de Dados { #testing-a-database }
Você pode estudar sobre bases de dados, SQL e SQLModel na <ahref="https://sqlmodel.tiangolo.com/"class="external-link"target="_blank">documentação de SQLModel</a>. 🤓
Você pode estudar sobre bases de dados, SQL e SQLModel na [documentação de SQLModel](https://sqlmodel.tiangolo.com/). 🤓
Aqui tem um mini <ahref="https://sqlmodel.tiangolo.com/tutorial/fastapi/"class="external-link"target="_blank">tutorial de como usar SQLModel com FastAPI</a>. ✨
Aqui tem um mini [tutorial de como usar SQLModel com FastAPI](https://sqlmodel.tiangolo.com/tutorial/fastapi/). ✨
Esse tutorial inclui uma seção sobre <ahref="https://sqlmodel.tiangolo.com/tutorial/fastapi/tests/"class="external-link"target="_blank">testar bases de dados SQL</a>. 😎
Esse tutorial inclui uma seção sobre [testar bases de dados SQL](https://sqlmodel.tiangolo.com/tutorial/fastapi/tests/). 😎
github-actions[bot]
4 months ago
Yurii Motov