mirror of https://github.com/tiangolo/fastapi.git
Merge branch 'master' into fix-duplicate-special-dependency-handling
This commit is contained in:
Peter Volf
GitHub
commit
5dcb1aa29d
|
|
@ -9,6 +9,10 @@ hide:
|
|||
|
||||
### Translations
|
||||
|
||||
* 🌐 Add Traditional Chinese translation for `docs/zh-hant/docs/fastapi-cli.md`. PR [#12444](https://github.com/fastapi/fastapi/pull/12444) by [@codingjenny](https://github.com/codingjenny).
|
||||
* 🌐 Add Traditional Chinese translation for `docs/zh-hant/docs/deployment/index.md`. PR [#12439](https://github.com/fastapi/fastapi/pull/12439) by [@codingjenny](https://github.com/codingjenny).
|
||||
* 🌐 Add Portuguese translation for `docs/pt/docs/how-to/testing-database.md`. PR [#12472](https://github.com/fastapi/fastapi/pull/12472) by [@GuilhermeRameh](https://github.com/GuilhermeRameh).
|
||||
* 🌐 Add Portuguese translation for `docs/pt/docs/how-to/custom-docs-ui-assets.md`. PR [#12473](https://github.com/fastapi/fastapi/pull/12473) by [@devluisrodrigues](https://github.com/devluisrodrigues).
|
||||
* 🌐 Add Portuguese translation for `docs/pt/docs/advanced/response-headers.md`. PR [#12458](https://github.com/fastapi/fastapi/pull/12458) by [@leonardopaloschi](https://github.com/leonardopaloschi).
|
||||
* 🌐 Add Traditional Chinese translation for `docs/zh-hant/docs/deployment/cloud.md`. PR [#12440](https://github.com/fastapi/fastapi/pull/12440) by [@codingjenny](https://github.com/codingjenny).
|
||||
* 🌐 Update Portuguese translation for `docs/pt/docs/python-types.md`. PR [#12428](https://github.com/fastapi/fastapi/pull/12428) by [@ceb10n](https://github.com/ceb10n).
|
||||
|
|
|
|||
|
|
@ -0,0 +1,205 @@
|
|||
# Recursos Estáticos Personalizados para a UI de Documentação (Hospedagem Própria)
|
||||
|
||||
A documentação da API usa **Swagger UI** e **ReDoc**, e cada um deles precisa de alguns arquivos JavaScript e CSS.
|
||||
|
||||
Por padrão, esses arquivos são fornecidos por um <abbr title="Content Delivery Network: Um serviço, normalmente composto por vários servidores, que fornece arquivos estáticos, como JavaScript e CSS. É comumente usado para providenciar esses arquivos do servidor mais próximo do cliente, melhorando o desempenho.">CDN</abbr>.
|
||||
|
||||
Mas é possível personalizá-los, você pode definir um CDN específico ou providenciar os arquivos você mesmo.
|
||||
|
||||
## CDN Personalizado para JavaScript e CSS
|
||||
|
||||
Vamos supor que você deseja usar um <abbr title="Content Delivery Network">CDN</abbr> diferente, por exemplo, você deseja usar `https://unpkg.com/`.
|
||||
|
||||
Isso pode ser útil se, por exemplo, você mora em um país que restringe algumas URLs.
|
||||
|
||||
### Desativar a documentação automática
|
||||
|
||||
O primeiro passo é desativar a documentação automática, pois por padrão, ela usa o CDN padrão.
|
||||
|
||||
Para desativá-los, defina suas URLs como `None` ao criar seu aplicativo `FastAPI`:
|
||||
|
||||
```Python hl_lines="8"
|
||||
{!../../docs_src/custom_docs_ui/tutorial001.py!}
|
||||
```
|
||||
|
||||
### Incluir a documentação personalizada
|
||||
|
||||
Agora você pode criar as *operações de rota* para a documentação personalizada.
|
||||
|
||||
Você pode reutilizar as funções internas do FastAPI para criar as páginas HTML para a documentação e passar os argumentos necessários:
|
||||
|
||||
* `openapi_url`: a URL onde a página HTML para a documentação pode obter o esquema OpenAPI para a sua API. Você pode usar aqui o atributo `app.openapi_url`.
|
||||
* `title`: o título da sua API.
|
||||
* `oauth2_redirect_url`: você pode usar `app.swagger_ui_oauth2_redirect_url` aqui para usar o padrão.
|
||||
* `swagger_js_url`: a URL onde a página HTML para a sua documentação do Swagger UI pode obter o arquivo **JavaScript**. Este é o URL do CDN personalizado.
|
||||
* `swagger_css_url`: a URL onde a página HTML para a sua documentação do Swagger UI pode obter o arquivo **CSS**. Este é o URL do CDN personalizado.
|
||||
|
||||
E de forma semelhante para o ReDoc...
|
||||
|
||||
```Python hl_lines="2-6 11-19 22-24 27-33"
|
||||
{!../../docs_src/custom_docs_ui/tutorial001.py!}
|
||||
```
|
||||
|
||||
/// tip | Dica
|
||||
|
||||
A *operação de rota* para `swagger_ui_redirect` é um auxiliar para quando você usa OAuth2.
|
||||
|
||||
Se você integrar sua API com um provedor OAuth2, você poderá autenticar e voltar para a documentação da API com as credenciais adquiridas. E interagir com ela usando a autenticação OAuth2 real.
|
||||
|
||||
Swagger UI lidará com isso nos bastidores para você, mas ele precisa desse auxiliar de "redirecionamento".
|
||||
|
||||
///
|
||||
|
||||
### Criar uma *operação de rota* para testar
|
||||
|
||||
Agora, para poder testar se tudo funciona, crie uma *operação de rota*:
|
||||
|
||||
```Python hl_lines="36-38"
|
||||
{!../../docs_src/custom_docs_ui/tutorial001.py!}
|
||||
```
|
||||
|
||||
### Teste
|
||||
|
||||
Agora, você deve ser capaz de ir para a documentação em <a href="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.
|
||||
|
||||
## Hospedagem Própria de JavaScript e CSS para a documentação
|
||||
|
||||
Hospedar o JavaScript e o CSS pode ser útil se, por exemplo, você precisa que seu aplicativo continue funcionando mesmo offline, sem acesso aberto à Internet, ou em uma rede local.
|
||||
|
||||
Aqui você verá como providenciar esses arquivos você mesmo, no mesmo aplicativo FastAPI, e configurar a documentação para usá-los.
|
||||
|
||||
### Estrutura de Arquivos do Projeto
|
||||
|
||||
Vamos supor que a estrutura de arquivos do seu projeto se pareça com isso:
|
||||
|
||||
```
|
||||
.
|
||||
├── app
|
||||
│ ├── __init__.py
|
||||
│ ├── main.py
|
||||
```
|
||||
|
||||
Agora crie um diretório para armazenar esses arquivos estáticos.
|
||||
|
||||
Sua nova estrutura de arquivos poderia se parecer com isso:
|
||||
|
||||
```
|
||||
.
|
||||
├── app
|
||||
│ ├── __init__.py
|
||||
│ ├── main.py
|
||||
└── static/
|
||||
```
|
||||
|
||||
### Baixe os arquivos
|
||||
|
||||
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...`.
|
||||
|
||||
**Swagger UI** usa os arquivos:
|
||||
|
||||
* <a href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js" class="external-link" target="_blank">`swagger-ui-bundle.js`</a>
|
||||
* <a href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css" class="external-link" target="_blank">`swagger-ui.css`</a>
|
||||
|
||||
E o **ReDoc** usa os arquivos:
|
||||
|
||||
* <a href="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js" class="external-link" target="_blank">`redoc.standalone.js`</a>
|
||||
|
||||
Depois disso, sua estrutura de arquivos deve se parecer com:
|
||||
|
||||
```
|
||||
.
|
||||
├── app
|
||||
│ ├── __init__.py
|
||||
│ ├── main.py
|
||||
└── static
|
||||
├── redoc.standalone.js
|
||||
├── swagger-ui-bundle.js
|
||||
└── swagger-ui.css
|
||||
```
|
||||
|
||||
### Prover os arquivos estáticos
|
||||
|
||||
* Importe `StaticFiles`.
|
||||
* "Monte" a instância `StaticFiles()` em um caminho específico.
|
||||
|
||||
```Python hl_lines="7 11"
|
||||
{!../../docs_src/custom_docs_ui/tutorial002.py!}
|
||||
```
|
||||
|
||||
### Teste os arquivos estáticos
|
||||
|
||||
Inicialize seu aplicativo e vá para <a href="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>.
|
||||
|
||||
Você deverá ver um arquivo JavaScript muito longo para o **ReDoc**.
|
||||
|
||||
Esse arquivo pode começar com algo como:
|
||||
|
||||
```JavaScript
|
||||
/*!
|
||||
* ReDoc - OpenAPI/Swagger-generated API Reference Documentation
|
||||
* -------------------------------------------------------------
|
||||
* Version: "2.0.0-rc.18"
|
||||
* Repo: https://github.com/Redocly/redoc
|
||||
*/
|
||||
!function(e,t){"object"==typeof exports&&"object"==typeof m
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
Isso confirma que você está conseguindo fornecer arquivos estáticos do seu aplicativo e que você colocou os arquivos estáticos para a documentação no local correto.
|
||||
|
||||
Agora, podemos configurar o aplicativo para usar esses arquivos estáticos para a documentação.
|
||||
|
||||
### Desativar a documentação automática para arquivos estáticos
|
||||
|
||||
Da mesma forma que ao usar um CDN personalizado, o primeiro passo é desativar a documentação automática, pois ela usa o CDN padrão.
|
||||
|
||||
Para desativá-los, defina suas URLs como `None` ao criar seu aplicativo `FastAPI`:
|
||||
|
||||
```Python hl_lines="9"
|
||||
{!../../docs_src/custom_docs_ui/tutorial002.py!}
|
||||
```
|
||||
|
||||
### Incluir a documentação personalizada para arquivos estáticos
|
||||
|
||||
E da mesma forma que com um CDN personalizado, agora você pode criar as *operações de rota* para a documentação personalizada.
|
||||
|
||||
Novamente, você pode reutilizar as funções internas do FastAPI para criar as páginas HTML para a documentação e passar os argumentos necessários:
|
||||
|
||||
* `openapi_url`: a URL onde a página HTML para a documentação pode obter o esquema OpenAPI para a sua API. Você pode usar aqui o atributo `app.openapi_url`.
|
||||
* `title`: o título da sua API.
|
||||
* `oauth2_redirect_url`: Você pode usar `app.swagger_ui_oauth2_redirect_url` aqui para usar o padrão.
|
||||
* `swagger_js_url`: a URL onde a página HTML para a sua documentação do Swagger UI pode obter o arquivo **JavaScript**. Este é o URL do CDN personalizado. **Este é o URL que seu aplicativo está fornecendo**.
|
||||
* `swagger_css_url`: a URL onde a página HTML para a sua documentação do Swagger UI pode obter o arquivo **CSS**. **Esse é o que seu aplicativo está fornecendo**.
|
||||
|
||||
E de forma semelhante para o ReDoc...
|
||||
|
||||
```Python hl_lines="2-6 14-22 25-27 30-36"
|
||||
{!../../docs_src/custom_docs_ui/tutorial002.py!}
|
||||
```
|
||||
|
||||
/// tip | Dica
|
||||
|
||||
A *operação de rota* para `swagger_ui_redirect` é um auxiliar para quando você usa OAuth2.
|
||||
|
||||
Se você integrar sua API com um provedor OAuth2, você poderá autenticar e voltar para a documentação da API com as credenciais adquiridas. E, então, interagir com ela usando a autenticação OAuth2 real.
|
||||
|
||||
Swagger UI lidará com isso nos bastidores para você, mas ele precisa desse auxiliar de "redirect".
|
||||
|
||||
///
|
||||
|
||||
### Criar uma *operação de rota* para testar arquivos estáticos
|
||||
|
||||
Agora, para poder testar se tudo funciona, crie uma *operação de rota*:
|
||||
|
||||
```Python hl_lines="39-41"
|
||||
{!../../docs_src/custom_docs_ui/tutorial002.py!}
|
||||
```
|
||||
|
||||
### Teste a UI de Arquivos Estáticos
|
||||
|
||||
Agora, você deve ser capaz de desconectar o WiFi, ir para a documentação em <a href="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.
|
||||
|
||||
E mesmo sem Internet, você será capaz de ver a documentação da sua API e interagir com ela.
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
# Testando a Base de Dados
|
||||
|
||||
Você pode estudar sobre bases de dados, SQL e SQLModel na <a href="https://sqlmodel.tiangolo.com/" class="external-link" target="_blank">documentação de SQLModel</a>. 🤓
|
||||
|
||||
Aqui tem um mini <a href="https://sqlmodel.tiangolo.com/tutorial/fastapi/" class="external-link" target="_blank">tutorial de como usar SQLModel com FastAPI</a>. ✨
|
||||
|
||||
Esse tutorial inclui uma sessão sobre <a href="https://sqlmodel.tiangolo.com/tutorial/fastapi/tests/" class="external-link" target="_blank">testar bases de dados SQL</a>. 😎
|
||||
|
|
@ -0,0 +1,21 @@
|
|||
# 部署
|
||||
|
||||
部署 **FastAPI** 應用程式相對容易。
|
||||
|
||||
## 部署是什麼意思
|
||||
|
||||
**部署** 應用程式指的是執行一系列必要的步驟，使其能夠 **讓使用者存取和使用**。
|
||||
|
||||
對於一個 **Web API**，部署通常涉及將其放置在 **遠端伺服器** 上，並使用性能優良且穩定的 **伺服器程式**，確保使用者能夠高效、無中斷地存取應用程式，且不會遇到問題。
|
||||
|
||||
這與 **開發** 階段形成鮮明對比，在 **開發** 階段，你會不斷更改程式碼、破壞程式碼、修復程式碼，然後停止和重新啟動伺服器等。
|
||||
|
||||
## 部署策略
|
||||
|
||||
根據你的使用場景和使用工具，有多種方法可以實現此目的。
|
||||
|
||||
你可以使用一些工具自行 **部署伺服器**，你也可以使用能為你完成部分工作的 **雲端服務**，或其他可能的選項。
|
||||
|
||||
我將向你展示在部署 **FastAPI** 應用程式時你可能應該記住的一些主要概念（儘管其中大部分適用於任何其他類型的 Web 應用程式）。
|
||||
|
||||
在接下來的部分中，你將看到更多需要記住的細節以及一些技巧。 ✨
|
||||
|
|
@ -0,0 +1,83 @@
|
|||
# FastAPI CLI
|
||||
|
||||
**FastAPI CLI** 是一個命令列程式，能用來運行你的 FastAPI 應用程式、管理你的 FastAPI 專案等。
|
||||
|
||||
當你安裝 FastAPI（例如使用 `pip install "fastapi[standard]"`），它會包含一個叫做 `fastapi-cli` 的套件，這個套件提供了 `fastapi` 命令。
|
||||
|
||||
要運行你的 FastAPI 應用程式來進行開發，你可以使用 `fastapi dev` 命令：
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ <font color="#4E9A06">fastapi</font> dev <u style="text-decoration-style:single">main.py</u>
|
||||
<font color="#3465A4">INFO </font> Using path <font color="#3465A4">main.py</font>
|
||||
<font color="#3465A4">INFO </font> Resolved absolute path <font color="#75507B">/home/user/code/awesomeapp/</font><font color="#AD7FA8">main.py</font>
|
||||
<font color="#3465A4">INFO </font> Searching for package file structure from directories with <font color="#3465A4">__init__.py</font> files
|
||||
<font color="#3465A4">INFO </font> Importing from <font color="#75507B">/home/user/code/</font><font color="#AD7FA8">awesomeapp</font>
|
||||
|
||||
╭─ <font color="#8AE234"><b>Python module file</b></font> ─╮
|
||||
│ │
|
||||
│ 🐍 main.py │
|
||||
│ │
|
||||
╰──────────────────────╯
|
||||
|
||||
<font color="#3465A4">INFO </font> Importing module <font color="#4E9A06">main</font>
|
||||
<font color="#3465A4">INFO </font> Found importable FastAPI app
|
||||
|
||||
╭─ <font color="#8AE234"><b>Importable FastAPI app</b></font> ─╮
|
||||
│ │
|
||||
│ <span style="background-color:#272822"><font color="#FF4689">from</font></span><span style="background-color:#272822"><font color="#F8F8F2"> main </font></span><span style="background-color:#272822"><font color="#FF4689">import</font></span><span style="background-color:#272822"><font color="#F8F8F2"> app</font></span><span style="background-color:#272822"> </span> │
|
||||
│ │
|
||||
╰──────────────────────────╯
|
||||
|
||||
<font color="#3465A4">INFO </font> Using import string <font color="#8AE234"><b>main:app</b></font>
|
||||
|
||||
<span style="background-color:#C4A000"><font color="#2E3436">╭────────── FastAPI CLI - Development mode ───────────╮</font></span>
|
||||
<span style="background-color:#C4A000"><font color="#2E3436">│ │</font></span>
|
||||
<span style="background-color:#C4A000"><font color="#2E3436">│ Serving at: http://127.0.0.1:8000 │</font></span>
|
||||
<span style="background-color:#C4A000"><font color="#2E3436">│ │</font></span>
|
||||
<span style="background-color:#C4A000"><font color="#2E3436">│ API docs: http://127.0.0.1:8000/docs │</font></span>
|
||||
<span style="background-color:#C4A000"><font color="#2E3436">│ │</font></span>
|
||||
<span style="background-color:#C4A000"><font color="#2E3436">│ Running in development mode, for production use: │</font></span>
|
||||
<span style="background-color:#C4A000"><font color="#2E3436">│ │</font></span>
|
||||
<span style="background-color:#C4A000"><font color="#2E3436">│ </font></span><span style="background-color:#C4A000"><font color="#555753"><b>fastapi run</b></font></span><span style="background-color:#C4A000"><font color="#2E3436"> │</font></span>
|
||||
<span style="background-color:#C4A000"><font color="#2E3436">│ │</font></span>
|
||||
<span style="background-color:#C4A000"><font color="#2E3436">╰─────────────────────────────────────────────────────╯</font></span>
|
||||
|
||||
<font color="#4E9A06">INFO</font>: Will watch for changes in these directories: ['/home/user/code/awesomeapp']
|
||||
<font color="#4E9A06">INFO</font>: Uvicorn running on <b>http://127.0.0.1:8000</b> (Press CTRL+C to quit)
|
||||
<font color="#4E9A06">INFO</font>: Started reloader process [<font color="#34E2E2"><b>2265862</b></font>] using <font color="#34E2E2"><b>WatchFiles</b></font>
|
||||
<font color="#4E9A06">INFO</font>: Started server process [<font color="#06989A">2265873</font>]
|
||||
<font color="#4E9A06">INFO</font>: Waiting for application startup.
|
||||
<font color="#4E9A06">INFO</font>: Application startup complete.
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
`fastapi` 命令列程式就是 **FastAPI CLI**。
|
||||
|
||||
FastAPI CLI 接收你的 Python 程式路徑（例如 `main.py`），並自動檢測 FastAPI 實例（通常命名為 `app`），確定正確的引入模組流程，然後運行該應用程式。
|
||||
|
||||
在生產環境，你應該使用 `fastapi run` 命令。 🚀
|
||||
|
||||
**FastAPI CLI** 內部使用了 <a href="https://www.uvicorn.org" class="external-link" target="_blank">Uvicorn</a>，這是一個高效能、適合生產環境的 ASGI 伺服器。 😎
|
||||
|
||||
## `fastapi dev`
|
||||
|
||||
執行 `fastapi dev` 會啟動開發模式。
|
||||
|
||||
預設情況下，**auto-reload** 功能是啟用的，當你對程式碼進行修改時，伺服器會自動重新載入。這會消耗較多資源，並且可能比禁用時更不穩定。因此，你應該只在開發環境中使用此功能。它也會在 IP 位址 `127.0.0.1` 上監聽，這是用於你的機器與自身通訊的 IP 位址（`localhost`）。
|
||||
|
||||
## `fastapi run`
|
||||
|
||||
執行 `fastapi run` 會以生產模式啟動 FastAPI。
|
||||
|
||||
預設情況下，**auto-reload** 功能是禁用的。它也會在 IP 位址 `0.0.0.0` 上監聽，表示會監聽所有可用的 IP 地址，這樣任何能與該機器通訊的人都可以公開存取它。這通常是你在生產環境中運行應用程式的方式，例如在容器中運行時。
|
||||
|
||||
在大多數情況下，你會（也應該）有一個「終止代理」來處理 HTTPS，這取決於你如何部署你的應用程式，你的服務供應商可能會為你做這件事，或者你需要自己設置它。
|
||||
|
||||
/// tip
|
||||
|
||||
你可以在[部署文件](deployment/index.md){.internal-link target=_blank}中了解更多相關資訊。
|
||||
|
||||
///
|
||||
Loading…
Reference in New Issue