diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 2fd46df6b..39ea7de52 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -62,7 +62,10 @@ jobs: env: PROJECT_NAME: fastapitiangolo BRANCH: ${{ ( github.event.workflow_run.head_repository.full_name == github.repository && github.event.workflow_run.head_branch == 'master' && 'main' ) || ( github.event.workflow_run.head_sha ) }} - uses: cloudflare/wrangler-action@v3 + # TODO: Use v3 when it's fixed, probably in v3.11 + # https://github.com/cloudflare/wrangler-action/issues/307 + uses: cloudflare/wrangler-action@v3.9 + # uses: cloudflare/wrangler-action@v3 with: apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} diff --git a/docs/en/data/external_links.yml b/docs/en/data/external_links.yml index dedbe87f4..9e411a631 100644 --- a/docs/en/data/external_links.yml +++ b/docs/en/data/external_links.yml @@ -339,6 +339,10 @@ Articles: link: https://qiita.com/mtitg/items/47770e9a562dd150631d title: FastAPI｜DB接続してCRUDするPython製APIサーバーを構築 Portuguese: + - author: Eduardo Mendes + author_link: https://bolha.us/@dunossauro + link: https://fastapidozero.dunossauro.com/ + title: FastAPI do ZERO - author: Jessica Temporal author_link: https://jtemporal.com/socials link: https://jtemporal.com/dicas-para-migrar-de-flask-para-fastapi-e-vice-versa/ diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index daaaa9c99..1720110ec 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -9,10 +9,17 @@ hide: ### Docs +* 📝 Add External Link: FastAPI do Zero. PR [#12533](https://github.com/fastapi/fastapi/pull/12533) by [@rennerocha](https://github.com/rennerocha). +* 📝 Fix minor typos. PR [#12516](https://github.com/fastapi/fastapi/pull/12516) by [@kkirsche](https://github.com/kkirsche). * 🌐 Fix rendering issue in translations. PR [#12509](https://github.com/fastapi/fastapi/pull/12509) by [@alejsdev](https://github.com/alejsdev). ### Translations +* 🌐 Add Portuguese translation for `docs/pt/docs/how-to/separate-openapi-schemas.md`. PR [#12518](https://github.com/fastapi/fastapi/pull/12518) by [@ilacftemp](https://github.com/ilacftemp). +* 🌐 Update Traditional Chinese translation for `docs/zh-hant/docs/deployment/index.md`. PR [#12521](https://github.com/fastapi/fastapi/pull/12521) by [@codingjenny](https://github.com/codingjenny). +* 🌐 Update Traditional Chinese translation for `docs/zh-hant/docs/deployment/cloud.md`. PR [#12522](https://github.com/fastapi/fastapi/pull/12522) by [@codingjenny](https://github.com/codingjenny). +* 🌐 Update Traditional Chinese translation for `docs/zh-hant/docs/how-to/index.md`. PR [#12523](https://github.com/fastapi/fastapi/pull/12523) by [@codingjenny](https://github.com/codingjenny). +* 🌐 Update Traditional Chinese translation for `docs/zh-hant/docs/tutorial/index.md`. PR [#12524](https://github.com/fastapi/fastapi/pull/12524) by [@codingjenny](https://github.com/codingjenny). * 🌐 Add Traditional Chinese translation for `docs/zh-hant/docs/how-to/index.md`. PR [#12468](https://github.com/fastapi/fastapi/pull/12468) by [@codingjenny](https://github.com/codingjenny). * 🌐 Add Traditional Chinese translation for `docs/zh-hant/docs/tutorial/index.md`. PR [#12466](https://github.com/fastapi/fastapi/pull/12466) by [@codingjenny](https://github.com/codingjenny). * 🌐 Add Portuguese translation for `docs/pt/docs/tutorial/header-param-models.md`. PR [#12437](https://github.com/fastapi/fastapi/pull/12437) by [@Joao-Pedro-P-Holanda](https://github.com/Joao-Pedro-P-Holanda). @@ -22,6 +29,7 @@ hide: ### Internal +* 👷 Update GitHub Action to deploy docs previews to handle missing deploy comments. PR [#12527](https://github.com/fastapi/fastapi/pull/12527) by [@tiangolo](https://github.com/tiangolo). * ⬆ [pre-commit.ci] pre-commit autoupdate. PR [#12505](https://github.com/fastapi/fastapi/pull/12505) by [@pre-commit-ci[bot]](https://github.com/apps/pre-commit-ci). ## 0.115.3 diff --git a/docs/pt/docs/how-to/separate-openapi-schemas.md b/docs/pt/docs/how-to/separate-openapi-schemas.md new file mode 100644 index 000000000..50d321d4c --- /dev/null +++ b/docs/pt/docs/how-to/separate-openapi-schemas.md @@ -0,0 +1,258 @@ +# Esquemas OpenAPI Separados para Entrada e Saída ou Não + +Ao usar **Pydantic v2**, o OpenAPI gerado é um pouco mais exato e **correto** do que antes. 😎 + +Inclusive, em alguns casos, ele terá até **dois JSON Schemas** no OpenAPI para o mesmo modelo Pydantic, para entrada e saída, dependendo se eles possuem **valores padrão**. + +Vamos ver como isso funciona e como alterar se for necessário. + +## Modelos Pydantic para Entrada e Saída + +Digamos que você tenha um modelo Pydantic com valores padrão, como este: + +//// tab | Python 3.10+ + +```Python hl_lines="7" +{!> ../../docs_src/separate_openapi_schemas/tutorial001_py310.py[ln:1-7]!} + +# Code below omitted 👇 +``` + +
+👀 Visualização completa do arquivo + +```Python +{!> ../../docs_src/separate_openapi_schemas/tutorial001_py310.py!} +``` + +
+ +//// + +//// tab | Python 3.9+ + +```Python hl_lines="9" +{!> ../../docs_src/separate_openapi_schemas/tutorial001_py39.py[ln:1-9]!} + +# Code below omitted 👇 +``` + +
+👀 Visualização completa do arquivo + +```Python +{!> ../../docs_src/separate_openapi_schemas/tutorial001_py39.py!} +``` + +
+ +//// + +//// tab | Python 3.8+ + +```Python hl_lines="9" +{!> ../../docs_src/separate_openapi_schemas/tutorial001.py[ln:1-9]!} + +# Code below omitted 👇 +``` + +
+👀 Visualização completa do arquivo + +```Python +{!> ../../docs_src/separate_openapi_schemas/tutorial001.py!} +``` + +
+ +//// + +### Modelo para Entrada + +Se você usar esse modelo como entrada, como aqui: + +//// tab | Python 3.10+ + +```Python hl_lines="14" +{!> ../../docs_src/separate_openapi_schemas/tutorial001_py310.py[ln:1-15]!} + +# Code below omitted 👇 +``` + +
+👀 Visualização completa do arquivo + +```Python +{!> ../../docs_src/separate_openapi_schemas/tutorial001_py310.py!} +``` + +
+ +//// + +//// tab | Python 3.9+ + +```Python hl_lines="16" +{!> ../../docs_src/separate_openapi_schemas/tutorial001_py39.py[ln:1-17]!} + +# Code below omitted 👇 +``` + +
+👀 Visualização completa do arquivo + +```Python +{!> ../../docs_src/separate_openapi_schemas/tutorial001_py39.py!} +``` + +
+ +//// + +//// tab | Python 3.8+ + +```Python hl_lines="16" +{!> ../../docs_src/separate_openapi_schemas/tutorial001.py[ln:1-17]!} + +# Code below omitted 👇 +``` + +
+👀 Visualização completa do arquivo + +```Python +{!> ../../docs_src/separate_openapi_schemas/tutorial001.py!} +``` + +
+ +//// + +... então o campo `description` não será obrigatório. Porque ele tem um valor padrão de `None`. + +### Modelo de Entrada na Documentação + +Você pode confirmar que na documentação, o campo `description` não tem um **asterisco vermelho**, não é marcado como obrigatório: + +
+ +
+ +### Modelo para Saída + +Mas se você usar o mesmo modelo como saída, como aqui: + +//// tab | Python 3.10+ + +```Python hl_lines="19" +{!> ../../docs_src/separate_openapi_schemas/tutorial001_py310.py!} +``` + +//// + +//// tab | Python 3.9+ + +```Python hl_lines="21" +{!> ../../docs_src/separate_openapi_schemas/tutorial001_py39.py!} +``` + +//// + +//// tab | Python 3.8+ + +```Python hl_lines="21" +{!> ../../docs_src/separate_openapi_schemas/tutorial001.py!} +``` + +//// + +... então, como `description` tem um valor padrão, se você **não retornar nada** para esse campo, ele ainda terá o **valor padrão**. + +### Modelo para Dados de Resposta de Saída + +Se você interagir com a documentação e verificar a resposta, mesmo que o código não tenha adicionado nada em um dos campos `description`, a resposta JSON contém o valor padrão (`null`): + +
+ +
+ +Isso significa que ele **sempre terá um valor**, só que às vezes o valor pode ser `None` (ou `null` em termos de JSON). + +Isso quer dizer que, os clientes que usam sua API não precisam verificar se o valor existe ou não, eles podem **assumir que o campo sempre estará lá**, mas que em alguns casos terá o valor padrão de `None`. + +A maneira de descrever isso no OpenAPI é marcar esse campo como **obrigatório**, porque ele sempre estará lá. + +Por causa disso, o JSON Schema para um modelo pode ser diferente dependendo se ele é usado para **entrada ou saída**: + +* para **entrada**, o `description` **não será obrigatório** +* para **saída**, ele será **obrigatório** (e possivelmente `None`, ou em termos de JSON, `null`) + +### Modelo para Saída na Documentação + +Você pode verificar o modelo de saída na documentação também, ambos `name` e `description` são marcados como **obrigatórios** com um **asterisco vermelho**: + +
+ +
+ +### Modelo para Entrada e Saída na Documentação + +E se você verificar todos os Schemas disponíveis (JSON Schemas) no OpenAPI, verá que há dois, um `Item-Input` e um `Item-Output`. + +Para `Item-Input`, `description` **não é obrigatório**, não tem um asterisco vermelho. + +Mas para `Item-Output`, `description` **é obrigatório**, tem um asterisco vermelho. + +
+ +
+ +Com esse recurso do **Pydantic v2**, sua documentação da API fica mais **precisa**, e se você tiver clientes e SDKs gerados automaticamente, eles serão mais precisos também, proporcionando uma melhor **experiência para desenvolvedores** e consistência. 🎉 + +## Não Separe Schemas + +Agora, há alguns casos em que você pode querer ter o **mesmo esquema para entrada e saída**. + +Provavelmente, o principal caso de uso para isso é se você já tem algum código de cliente/SDK gerado automaticamente e não quer atualizar todo o código de cliente/SDK gerado ainda, você provavelmente vai querer fazer isso em algum momento, mas talvez não agora. + +Nesse caso, você pode desativar esse recurso no **FastAPI**, com o parâmetro `separate_input_output_schemas=False`. + +/// info | Informação + +O suporte para `separate_input_output_schemas` foi adicionado no FastAPI `0.102.0`. 🤓 + +/// + +//// tab | Python 3.10+ + +```Python hl_lines="10" +{!> ../../docs_src/separate_openapi_schemas/tutorial002_py310.py!} +``` + +//// + +//// tab | Python 3.9+ + +```Python hl_lines="12" +{!> ../../docs_src/separate_openapi_schemas/tutorial002_py39.py!} +``` + +//// + +//// tab | Python 3.8+ + +```Python hl_lines="12" +{!> ../../docs_src/separate_openapi_schemas/tutorial002.py!} +``` + +//// + +### Mesmo Esquema para Modelos de Entrada e Saída na Documentação + +E agora haverá um único esquema para entrada e saída para o modelo, apenas `Item`, e `description` **não será obrigatório**: + +
+ +
+ +Esse é o mesmo comportamento do Pydantic v1. 🤓 diff --git a/docs/zh-hant/docs/deployment/cloud.md b/docs/zh-hant/docs/deployment/cloud.md index 5d645b6c2..29ebe3ff5 100644 --- a/docs/zh-hant/docs/deployment/cloud.md +++ b/docs/zh-hant/docs/deployment/cloud.md @@ -1,14 +1,14 @@ # 在雲端部署 FastAPI -你幾乎可以使用 **任何雲端供應商** 來部署你的 FastAPI 應用程式。 +你幾乎可以使用**任何雲端供應商**來部署你的 FastAPI 應用程式。 在大多數情況下，主要的雲端供應商都有部署 FastAPI 的指南。 ## 雲端供應商 - 贊助商 -一些雲端供應商 ✨ [**贊助 FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨，這確保了 FastAPI 及其 **生態系統** 持續健康地 **發展**。 +一些雲端供應商 ✨ [**贊助 FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨，這確保了 FastAPI 及其**生態系統**持續健康地**發展**。 -這也展現了他們對 FastAPI 和其 **社群**（包括你）的真正承諾，他們不僅希望為你提供 **優質的服務**，還希望確保你擁有一個 **良好且健康的框架**：FastAPI。🙇 +這也展現了他們對 FastAPI 和其**社群**（包括你）的真正承諾，他們不僅希望為你提供**優質的服務**，還希望確保你擁有一個**良好且健康的框架**：FastAPI。🙇 你可能會想嘗試他們的服務，以下有他們的指南： diff --git a/docs/zh-hant/docs/deployment/index.md b/docs/zh-hant/docs/deployment/index.md index e760b3d16..1726562b4 100644 --- a/docs/zh-hant/docs/deployment/index.md +++ b/docs/zh-hant/docs/deployment/index.md @@ -4,17 +4,17 @@ ## 部署是什麼意思 -**部署** 應用程式指的是執行一系列必要的步驟，使其能夠 **讓使用者存取和使用**。 +**部署**應用程式指的是執行一系列必要的步驟，使其能夠**讓使用者存取和使用**。 -對於一個 **Web API**，部署通常涉及將其放置在 **遠端伺服器** 上，並使用性能優良且穩定的 **伺服器程式**，確保使用者能夠高效、無中斷地存取應用程式，且不會遇到問題。 +對於一個 **Web API**，部署通常涉及將其放置在**遠端伺服器**上，並使用性能優良且穩定的**伺服器程式**，確保使用者能夠高效、無中斷地存取應用程式，且不會遇到問題。 -這與 **開發** 階段形成鮮明對比，在 **開發** 階段，你會不斷更改程式碼、破壞程式碼、修復程式碼，然後停止和重新啟動伺服器等。 +這與**開發**階段形成鮮明對比，在**開發**階段，你會不斷更改程式碼、破壞程式碼、修復程式碼，然後停止和重新啟動伺服器等。 ## 部署策略 根據你的使用場景和使用工具，有多種方法可以實現此目的。 -你可以使用一些工具自行 **部署伺服器**，你也可以使用能為你完成部分工作的 **雲端服務**，或其他可能的選項。 +你可以使用一些工具自行**部署伺服器**，你也可以使用能為你完成部分工作的**雲端服務**，或其他可能的選項。 我將向你展示在部署 **FastAPI** 應用程式時你可能應該記住的一些主要概念（儘管其中大部分適用於任何其他類型的 Web 應用程式）。 diff --git a/docs/zh-hant/docs/how-to/index.md b/docs/zh-hant/docs/how-to/index.md index d668b5b7a..db740140d 100644 --- a/docs/zh-hant/docs/how-to/index.md +++ b/docs/zh-hant/docs/how-to/index.md @@ -1,13 +1,13 @@ # 使用指南 - 範例集 -在這裡，你將會看到 **不同主題** 的範例或「如何使用」的指南。 +在這裡，你將會看到**不同主題**的範例或「如何使用」的指南。 -大多數這些想法都是 **獨立** 的，在大多數情況下，你只需要研究那些直接適用於 **你的專案** 的東西。 +大多數這些想法都是**獨立**的，在大多數情況下，你只需要研究那些直接適用於**你的專案**的東西。 如果有些東西看起來很有趣且對你的專案很有用的話再去讀它，否則你可能可以跳過它們。 /// tip -如果你想要以結構化的方式 **學習 FastAPI**（推薦），請前往[教學 - 使用者指南](../tutorial/index.md){.internal-link target=_blank}逐章閱讀。 +如果你想要以結構化的方式**學習 FastAPI**（推薦），請前往[教學 - 使用者指南](../tutorial/index.md){.internal-link target=_blank}逐章閱讀。 /// diff --git a/docs/zh-hant/docs/tutorial/index.md b/docs/zh-hant/docs/tutorial/index.md index 34f504851..2aaa78b22 100644 --- a/docs/zh-hant/docs/tutorial/index.md +++ b/docs/zh-hant/docs/tutorial/index.md @@ -61,7 +61,7 @@ $ fastapi dev fastapi dev @@ -93,10 +93,10 @@ $ pip install "fastapi[standard]" ## 進階使用者指南 -還有一個 **進階使用者指南** 你可以稍後閱讀。 +還有一個**進階使用者指南**你可以稍後閱讀。 -**進階使用者指南** 建立在這個教學之上，使用相同的概念，並教你一些額外的功能。 +**進階使用者指南**建立在這個教學之上，使用相同的概念，並教你一些額外的功能。 -但首先你應該閱讀 **教學 - 使用者指南**（你正在閱讀的內容）。 +但首先你應該閱讀**教學 - 使用者指南**（你正在閱讀的內容）。 -它被設計成你可以使用 **教學 - 使用者指南** 來建立一個完整的應用程式，然後根據你的需求，使用一些額外的想法來擴展它。 +它被設計成你可以使用**教學 - 使用者指南**來建立一個完整的應用程式，然後根據你的需求，使用一些額外的想法來擴展它。 diff --git a/fastapi/param_functions.py b/fastapi/param_functions.py index 7ddaace25..b3621626c 100644 --- a/fastapi/param_functions.py +++ b/fastapi/param_functions.py @@ -2298,7 +2298,7 @@ def Security( # noqa: N802 dependency. The term "scope" comes from the OAuth2 specification, it seems to be - intentionaly vague and interpretable. It normally refers to permissions, + intentionally vague and interpretable. It normally refers to permissions, in cases to roles. These scopes are integrated with OpenAPI (and the API docs at `/docs`). diff --git a/fastapi/security/oauth2.py b/fastapi/security/oauth2.py index 9720cace0..6adc55bfe 100644 --- a/fastapi/security/oauth2.py +++ b/fastapi/security/oauth2.py @@ -52,7 +52,7 @@ class OAuth2PasswordRequestForm: ``` Note that for OAuth2 the scope `items:read` is a single scope in an opaque string. - You could have custom internal logic to separate it by colon caracters (`:`) or + You could have custom internal logic to separate it by colon characters (`:`) or similar, and get the two parts `items` and `read`. Many applications do that to group and organize permissions, you could do it as well in your application, just know that that it is application specific, it's not part of the specification. @@ -194,7 +194,7 @@ class OAuth2PasswordRequestFormStrict(OAuth2PasswordRequestForm): ``` Note that for OAuth2 the scope `items:read` is a single scope in an opaque string. - You could have custom internal logic to separate it by colon caracters (`:`) or + You could have custom internal logic to separate it by colon characters (`:`) or similar, and get the two parts `items` and `read`. Many applications do that to group and organize permissions, you could do it as well in your application, just know that that it is application specific, it's not part of the specification.