-请记住，当您一般读到“服务器”这个名词时，它可能指的是这两者之一。
+```console
+$
fastapi run
main.py
-当提到远程主机时，通常将其称为**服务器**，但也称为**机器**(machine)、**VM**（虚拟机）、**节点**。 这些都是指某种类型的远程计算机，通常运行 Linux，您可以在其中运行程序。
+
FastAPI Starting production server 🚀
+ Searching for package file structure from directories
+ with
__init__.py files
+ Importing from
/home/user/code/awesomeapp
-## 安装服务器程序
+
module 🐍 main.py
-您可以使用以下命令安装 ASGI 兼容服务器：
+
code Importing the FastAPI app object from the module with
+ the following code:
-//// tab | Uvicorn
+
from main import app
-*
Uvicorn，一个快如闪电 ASGI 服务器，基于 uvloop 和 httptools 构建。
+
app Using import string:
main:app
-
+ server Server started at http://0.0.0.0:8000
+ server Documentation at http://0.0.0.0:8000/docs
-```console
-$ pip install "uvicorn[standard]"
+ Logs:
----> 100%
+ INFO Started server process [2306215]
+ INFO Waiting for application startup.
+ INFO Application startup complete.
+ INFO Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C
+ to quit)
```
-/// tip
+这在大多数情况下都能正常运行。😎
-通过添加`standard`，Uvicorn 将安装并使用一些推荐的额外依赖项。
+例如，您可以使用该命令在容器、服务器等环境中启动您的 **FastAPI** 应用。
-其中包括`uvloop`，它是`asyncio`的高性能替代品，它提供了巨大的并发性能提升。
+## ASGI 服务器
-///
+让我们深入了解一些细节。
-////
+FastAPI 使用了一种用于构建 Python Web 框架和服务器的标准，称为
ASGI。FastAPI 本质上是一个 ASGI Web 框架。
-//// tab | Hypercorn
+要在远程服务器上运行 **FastAPI** 应用（或任何其他 ASGI 应用），您需要一个 ASGI 服务器程序，例如 **Uvicorn**。它是 `fastapi` 命令默认使用的 ASGI 服务器。
-*
Hypercorn，一个也与 HTTP/2 兼容的 ASGI 服务器。
-
-
+除此之外，还有其他一些可选的 ASGI 服务器，例如：
-```console
-$ pip install hypercorn
-
----> 100%
-```
-
-
+*
Uvicorn：高性能 ASGI 服务器。
+*
Hypercorn：与 HTTP/2 和 Trio 等兼容的 ASGI 服务器。
+*
Daphne：为 Django Channels 构建的 ASGI 服务器。
+*
Granian：基于 Rust 的 HTTP 服务器，专为 Python 应用设计。
+*
NGINX Unit：NGINX Unit 是一个轻量级且灵活的 Web 应用运行时环境。
-...或任何其他 ASGI 服务器。
+## 服务器主机和服务器程序
-////
+关于名称，有一个小细节需要记住。 💡
-## 运行服务器程序
+“**服务器**”一词通常用于指远程/云计算机（物理机或虚拟机）以及在该计算机上运行的程序（例如 Uvicorn）。
-您可以按照之前教程中的相同方式运行应用程序，但不使用`--reload`选项，例如：
+请记住，当您一般读到“服务器”这个名词时，它可能指的是这两者之一。
-//// tab | Uvicorn
+当提到远程主机时，通常将其称为**服务器**，但也称为**机器**(machine)、**VM**（虚拟机）、**节点**。 这些都是指某种类型的远程计算机，通常运行 Linux，您可以在其中运行程序。
-
-```console
-$ uvicorn main:app --host 0.0.0.0 --port 80
+## 安装服务器程序
-INFO: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit)
-```
+当您安装 FastAPI 时，它自带一个生产环境服务器——Uvicorn，并且您可以使用 `fastapi run` 命令来启动它。
-
+不过，您也可以手动安装 ASGI 服务器。
-////
+请确保您创建并激活一个[虚拟环境](../virtual-environments.md){.internal-link target=_blank}，然后再安装服务器应用程序。
-//// tab | Hypercorn
+例如，要安装 Uvicorn，可以运行以下命令：
```console
-$ hypercorn main:app --bind 0.0.0.0:80
+$ pip install "uvicorn[standard]"
-Running on 0.0.0.0:8080 over http (CTRL + C to quit)
+---> 100%
```
-////
+类似的流程也适用于任何其他 ASGI 服务器程序。
-/// warning
+/// tip
-如果您正在使用`--reload`选项，请记住删除它。
+通过添加 `standard` 选项，Uvicorn 将安装并使用一些推荐的额外依赖项。
- `--reload` 选项消耗更多资源，并且更不稳定。
+其中包括 `uvloop`，这是 `asyncio` 的高性能替代方案，能够显著提升并发性能。
- 它在**开发**期间有很大帮助，但您**不应该**在**生产环境**中使用它。
+当您使用 `pip install "fastapi[standard]"` 安装 FastAPI 时，实际上也会安装 `uvicorn[standard]`。
///
-## Hypercorn with Trio
-
-Starlette 和 **FastAPI** 基于
AnyIO， 所以它们才能同时与 Python 的标准库
asyncio 和
Trio 兼容。
-
-尽管如此，Uvicorn 目前仅与 asyncio 兼容，并且通常使用
`uvloop`, 它是`asyncio`的高性能替代品。
-
-但如果你想直接使用**Trio**，那么你可以使用**Hypercorn**，因为它支持它。 ✨
-
-### 安装具有 Trio 的 Hypercorn
+## 运行服务器程序
-首先，您需要安装具有 Trio 支持的 Hypercorn：
+如果您手动安装了 ASGI 服务器，通常需要以特定格式传递一个导入字符串，以便服务器能够正确导入您的 FastAPI 应用：
```console
-$ pip install "hypercorn[trio]"
----> 100%
+$ uvicorn main:app --host 0.0.0.0 --port 80
+
+INFO: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit)
```
-### Run with Trio
+/// note
-然后你可以传递值`trio`给命令行选项`--worker-class`:
+命令 `uvicorn main:app` 的含义如下：
-
+* `main`：指的是 `main.py` 文件（即 Python “模块”）。
+* `app`：指的是 `main.py` 文件中通过 `app = FastAPI()` 创建的对象。
-```console
-$ hypercorn main:app --worker-class trio
+它等价于以下导入语句：
+
+```Python
+from main import app
```
-
+///
+
+每种 ASGI 服务器程序通常都会有类似的命令，您可以在它们的官方文档中找到更多信息。
+
+/// warning
+
+Uvicorn 和其他服务器支持 `--reload` 选项，该选项在开发过程中非常有用。
-这将通过您的应用程序启动 Hypercorn，并使用 Trio 作为后端。
+但 `--reload` 选项会消耗更多资源，且相对不稳定。
-现在您可以在应用程序内部使用 Trio。 或者更好的是，您可以使用 AnyIO，使您的代码与 Trio 和 asyncio 兼容。 🎉
+它对于**开发阶段**非常有帮助，但在**生产环境**中**不应该**使用。
+
+///
## 部署概念
-这些示例运行服务器程序（例如 Uvicorn），启动**单个进程**，在所有 IP（`0.0.0.0`)上监听预定义端口（例如`80`)。
+这些示例运行服务器程序（例如 Uvicorn），启动**单个进程**，在所有 IP（`0.0.0.0`）上监听预定义端口（例如`80`）。
这是基本思路。 但您可能需要处理一些其他事情，例如：
* 安全性 - HTTPS
* 启动时运行
* 重新启动
-* Replication（运行的进程数）
+* 复制（运行的进程数）
* 内存
* 开始前的步骤
diff --git a/docs/zh/docs/deployment/server-workers.md b/docs/zh/docs/deployment/server-workers.md
index eb0252a5c..e46ba7a09 100644
--- a/docs/zh/docs/deployment/server-workers.md
+++ b/docs/zh/docs/deployment/server-workers.md
@@ -1,4 +1,4 @@
-# Server Workers - Gunicorn with Uvicorn
+# 服务器工作进程（Workers） - 使用 Uvicorn 的多工作进程模式
让我们回顾一下之前的部署概念：
@@ -9,125 +9,79 @@
* 内存
* 启动前的先前步骤
-到目前为止，通过文档中的所有教程，您可能已经在**单个进程**上运行了像 Uvicorn 这样的**服务器程序**。
+到目前为止，在文档中的所有教程中，您可能一直是在运行一个**服务器程序**，例如使用 `fastapi` 命令来启动 Uvicorn，而它默认运行的是**单进程模式**。
-部署应用程序时，您可能希望进行一些**进程复制**，以利用**多核**并能够处理更多请求。
+部署应用程序时，您可能希望进行一些**进程复制**，以利用**多核** CPU 并能够处理更多请求。
正如您在上一章有关[部署概念](concepts.md){.internal-link target=_blank}中看到的，您可以使用多种策略。
-在这里我将向您展示如何将
**Gunicorn** 与 **Uvicorn worker 进程** 一起使用。
+在本章节中，我将向您展示如何使用 `fastapi` 命令或直接使用 `uvicorn` 命令以**多工作进程模式**运行 **Uvicorn**。
/// info
如果您正在使用容器，例如 Docker 或 Kubernetes，我将在下一章中告诉您更多相关信息：[容器中的 FastAPI - Docker](docker.md){.internal-link target=_blank}。
-特别是，当在 **Kubernetes** 上运行时，您可能**不想**使用 Gunicorn，而是运行 **每个容器一个 Uvicorn 进程**，但我将在本章后面告诉您这一点。
+比较特别的是，在 **Kubernetes** 环境中运行时，您通常**不需要**使用多个工作进程，而是**每个容器运行一个 Uvicorn 进程**。不过，我会在本章节的后续部分详细介绍这一点。
///
-## Gunicorn with Uvicorn Workers
+## 多个工作进程
-**Gunicorn**主要是一个使用**WSGI标准**的应用服务器。 这意味着 Gunicorn 可以为 Flask 和 Django 等应用程序提供服务。 Gunicorn 本身与 **FastAPI** 不兼容，因为 FastAPI 使用最新的 **
ASGI 标准**。
+您可以使用 `--workers` 命令行选项来启动多个工作进程：
-但 Gunicorn 支持充当 **进程管理器** 并允许用户告诉它要使用哪个特定的 **worker类**。 然后 Gunicorn 将使用该类启动一个或多个 **worker进程**。
+//// tab | `fastapi`
-**Uvicorn** 有一个 Gunicorn 兼容的worker类。
-
-使用这种组合，Gunicorn 将充当 **进程管理器**，监听 **端口** 和 **IP**。 它会将通信**传输**到运行**Uvicorn类**的worker进程。
-
-然后与Gunicorn兼容的**Uvicorn worker**类将负责将Gunicorn发送的数据转换为ASGI标准以供FastAPI使用。
-
-## 安装 Gunicorn 和 Uvicorn
+如果您使用 `fastapi` 命令：
```console
-$ pip install "uvicorn[standard]" gunicorn
-
----> 100%
-```
-
-
+$
fastapi run --workers 4
main.py
-这将安装带有`standard`扩展包（以获得高性能）的 Uvicorn 和 Gunicorn。
+
FastAPI Starting production server 🚀
-## Run Gunicorn with Uvicorn Workers
+ Searching for package file structure from directories with
+
__init__.py files
+ Importing from
/home/user/code/awesomeapp
-接下来你可以通过以下命令运行Gunicorn:
-
-
-
-```console
-$ gunicorn main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:80
-
-[19499] [INFO] Starting gunicorn 20.1.0
-[19499] [INFO] Listening at: http://0.0.0.0:80 (19499)
-[19499] [INFO] Using worker: uvicorn.workers.UvicornWorker
-[19511] [INFO] Booting worker with pid: 19511
-[19513] [INFO] Booting worker with pid: 19513
-[19514] [INFO] Booting worker with pid: 19514
-[19515] [INFO] Booting worker with pid: 19515
-[19511] [INFO] Started server process [19511]
-[19511] [INFO] Waiting for application startup.
-[19511] [INFO] Application startup complete.
-[19513] [INFO] Started server process [19513]
-[19513] [INFO] Waiting for application startup.
-[19513] [INFO] Application startup complete.
-[19514] [INFO] Started server process [19514]
-[19514] [INFO] Waiting for application startup.
-[19514] [INFO] Application startup complete.
-[19515] [INFO] Started server process [19515]
-[19515] [INFO] Waiting for application startup.
-[19515] [INFO] Application startup complete.
-```
-
-
+
module 🐍 main.py
+
code Importing the FastAPI app object from the module with the
+ following code:
-让我们看看每个选项的含义：
+
from main import app
-* `main:app`：这与 Uvicorn 使用的语法相同，`main` 表示名为"`main`"的 Python 模块，因此是文件 `main.py`。 `app` 是 **FastAPI** 应用程序的变量名称。
- * 你可以想象 `main:app` 相当于一个 Python `import` 语句，例如：
+
app Using import string:
main:app
- ```Python
- from main import app
- ```
+
server Server started at
http://0.0.0.0:8000
+
server Documentation at
http://0.0.0.0:8000/docs
- * 因此，`main:app` 中的冒号相当于 `from main import app` 中的 Python `import` 部分。
+ Logs:
-* `--workers`：要使用的worker进程数量，每个进程将运行一个 Uvicorn worker进程，在本例中为 4 个worker进程。
-
-* `--worker-class`：在worker进程中使用的与 Gunicorn 兼容的工作类。
- * 这里我们传递了 Gunicorn 可以导入和使用的类：
-
- ```Python
- import uvicorn.workers.UvicornWorker
- ```
-
-* `--bind`：这告诉 Gunicorn 要监听的 IP 和端口，使用冒号 (`:`) 分隔 IP 和端口。
- * 如果您直接运行 Uvicorn，则可以使用`--host 0.0.0.0`和`--port 80`，而不是`--bind 0.0.0.0:80`（Gunicorn 选项）。
-
-
-在输出中，您可以看到它显示了每个进程的 **PID**（进程 ID）（它只是一个数字）。
-
-你可以看到：
-
-* Gunicorn **进程管理器** 以 PID `19499` 开头（在您的情况下，它将是一个不同的数字）。
-* 然后它开始`Listening at: http://0.0.0.0:80`。
-* 然后它检测到它必须使用 `uvicorn.workers.UvicornWorker` 处的worker类。
-* 然后它启动**4个worker**，每个都有自己的PID：`19511`、`19513`、`19514`和`19515`。
-
-Gunicorn 还将负责管理**死进程**和**重新启动**新进程（如果需要保持worker数量）。 因此，这在一定程度上有助于上面列表中**重启**的概念。
-
-尽管如此，您可能还希望有一些外部的东西，以确保在必要时**重新启动 Gunicorn**，并且**在启动时运行它**等。
+
INFO Uvicorn running on
http://0.0.0.0:8000 (Press CTRL+C to
+ quit
)
+
INFO Started parent process
[27365]
+
INFO Started server process
[27368]
+
INFO Started server process
[27369]
+
INFO Started server process
[27370]
+
INFO Started server process
[27367]
+
INFO Waiting for application startup.
+
INFO Waiting for application startup.
+
INFO Waiting for application startup.
+
INFO Waiting for application startup.
+
INFO Application startup complete.
+
INFO Application startup complete.
+
INFO Application startup complete.
+
INFO Application startup complete.
+```
-## Uvicorn with Workers
+
@@ -151,13 +105,15 @@ $ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4
+////
+
这里唯一的新选项是 `--workers` 告诉 Uvicorn 启动 4 个工作进程。
-您还可以看到它显示了每个进程的 **PID**，父进程（这是 **进程管理器**）的 PID 为`27365`，每个工作进程的 PID 为：`27368`、`27369`， `27370`和`27367`。
+您还可以看到它显示了每个进程的 **PID**，父进程（这是**进程管理器**）的 PID 为`27365`，每个工作进程的 PID 为：`27368`、`27369`， `27370`和`27367`。
## 部署概念
-在这里，您了解了如何使用 **Gunicorn**（或 Uvicorn）管理 **Uvicorn 工作进程**来**并行**应用程序的执行，利用 CPU 中的 **多核**，并 能够满足**更多请求**。
+在这里，您学习了如何使用多个**工作进程（workers）**来让应用程序的执行**并行化**，充分利用 CPU 的**多核性能**，并能够处理**更多的请求**。
从上面的部署概念列表来看，使用worker主要有助于**复制**部分，并对**重新启动**有一点帮助，但您仍然需要照顾其他部分：
@@ -170,15 +126,13 @@ $ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4
## 容器和 Docker
-在关于 [容器中的 FastAPI - Docker](docker.md){.internal-link target=_blank} 的下一章中，我将介绍一些可用于处理其他 **部署概念** 的策略。
-
-我还将向您展示 **官方 Docker 镜像**，其中包括 **Gunicorn 和 Uvicorn worker** 以及一些对简单情况有用的默认配置。
+在关于 [容器中的 FastAPI - Docker](docker.md){.internal-link target=_blank} 的下一章中，我将介绍一些可用于处理其他**部署概念**的策略。
-在那里，我还将向您展示如何 **从头开始构建自己的镜像** 以运行单个 Uvicorn 进程（没有 Gunicorn）。 这是一个简单的过程，并且可能是您在使用像 **Kubernetes** 这样的分布式容器管理系统时想要做的事情。
+我将向您展示如何**从零开始构建自己的镜像**，以运行一个单独的 Uvicorn 进程。这个过程相对简单，并且在使用 **Kubernetes** 等分布式容器管理系统时，这通常是您需要采取的方法。
## 回顾
-您可以使用**Gunicorn**（或Uvicorn）作为Uvicorn工作进程的进程管理器，以利用**多核CPU**，**并行运行多个进程**。
+您可以在使用 `fastapi` 或 `uvicorn` 命令时，通过 `--workers` CLI 选项启用多个工作进程（workers），以充分利用**多核 CPU**，以**并行运行多个进程**。
如果您要设置**自己的部署系统**，同时自己处理其他部署概念，则可以使用这些工具和想法。
diff --git a/docs/zh/docs/tutorial/first-steps.md b/docs/zh/docs/tutorial/first-steps.md
index c4ff460e0..80a34116a 100644
--- a/docs/zh/docs/tutorial/first-steps.md
+++ b/docs/zh/docs/tutorial/first-steps.md
@@ -11,26 +11,42 @@
```console
-$ pip install "fastapi[all]"
+$ pip install "fastapi[standard]"
---> 100%
```
-......以上安装还包括了 `uvicorn`，你可以将其用作运行代码的服务器。
-
/// note
-你也可以分开来安装。
-
-假如你想将应用程序部署到生产环境，你可能要执行以下操作：
-
-```
-pip install fastapi
-```
-
-并且安装`uvicorn`来作为服务器：
-
-```
-pip install "uvicorn[standard]"
-```
+当您使用 `pip install "fastapi[standard]"` 进行安装时，它会附带一些默认的可选标准依赖项。
-然后对你想使用的每个可选依赖项也执行相同的操作。
+如果您不想安装这些可选依赖，可以选择安装 `pip install fastapi`。
///
## 进阶用户指南
-在本**教程-用户指南**之后，你可以阅读**进阶用户指南**。
+在本**教程-用户指南**之后，您可以阅读**进阶用户指南**。
**进阶用户指南**以本教程为基础，使用相同的概念，并教授一些额外的特性。
-但是你应该先阅读**教程-用户指南**（即你现在正在阅读的内容）。
+但是您应该先阅读**教程-用户指南**（即您现在正在阅读的内容）。
-教程经过精心设计，使你可以仅通过**教程-用户指南**来开发一个完整的应用程序，然后根据你的需要，使用**进阶用户指南**中的一些其他概念，以不同的方式来扩展它。
+教程经过精心设计，使您可以仅通过**教程-用户指南**来开发一个完整的应用程序，然后根据您的需要，使用**进阶用户指南**中的一些其他概念，以不同的方式来扩展它。
diff --git a/docs_src/header_param_models/tutorial003.py b/docs_src/header_param_models/tutorial003.py
new file mode 100644
index 000000000..dc2eb74bd
--- /dev/null
+++ b/docs_src/header_param_models/tutorial003.py
@@ -0,0 +1,19 @@
+from typing import List, Union
+
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ host: str
+ save_data: bool
+ if_modified_since: Union[str, None] = None
+ traceparent: Union[str, None] = None
+ x_tag: List[str] = []
+
+
+@app.get("/items/")
+async def read_items(headers: CommonHeaders = Header(convert_underscores=False)):
+ return headers
diff --git a/docs_src/header_param_models/tutorial003_an.py b/docs_src/header_param_models/tutorial003_an.py
new file mode 100644
index 000000000..e3edb1189
--- /dev/null
+++ b/docs_src/header_param_models/tutorial003_an.py
@@ -0,0 +1,22 @@
+from typing import List, Union
+
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+from typing_extensions import Annotated
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ host: str
+ save_data: bool
+ if_modified_since: Union[str, None] = None
+ traceparent: Union[str, None] = None
+ x_tag: List[str] = []
+
+
+@app.get("/items/")
+async def read_items(
+ headers: Annotated[CommonHeaders, Header(convert_underscores=False)],
+):
+ return headers
diff --git a/docs_src/header_param_models/tutorial003_an_py310.py b/docs_src/header_param_models/tutorial003_an_py310.py
new file mode 100644
index 000000000..07bfa83bf
--- /dev/null
+++ b/docs_src/header_param_models/tutorial003_an_py310.py
@@ -0,0 +1,21 @@
+from typing import Annotated
+
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ host: str
+ save_data: bool
+ if_modified_since: str | None = None
+ traceparent: str | None = None
+ x_tag: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(
+ headers: Annotated[CommonHeaders, Header(convert_underscores=False)],
+):
+ return headers
diff --git a/docs_src/header_param_models/tutorial003_an_py39.py b/docs_src/header_param_models/tutorial003_an_py39.py
new file mode 100644
index 000000000..8be6b01d0
--- /dev/null
+++ b/docs_src/header_param_models/tutorial003_an_py39.py
@@ -0,0 +1,21 @@
+from typing import Annotated, Union
+
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ host: str
+ save_data: bool
+ if_modified_since: Union[str, None] = None
+ traceparent: Union[str, None] = None
+ x_tag: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(
+ headers: Annotated[CommonHeaders, Header(convert_underscores=False)],
+):
+ return headers
diff --git a/docs_src/header_param_models/tutorial003_py310.py b/docs_src/header_param_models/tutorial003_py310.py
new file mode 100644
index 000000000..65e92a28c
--- /dev/null
+++ b/docs_src/header_param_models/tutorial003_py310.py
@@ -0,0 +1,17 @@
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ host: str
+ save_data: bool
+ if_modified_since: str | None = None
+ traceparent: str | None = None
+ x_tag: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(headers: CommonHeaders = Header(convert_underscores=False)):
+ return headers
diff --git a/docs_src/header_param_models/tutorial003_py39.py b/docs_src/header_param_models/tutorial003_py39.py
new file mode 100644
index 000000000..848c34111
--- /dev/null
+++ b/docs_src/header_param_models/tutorial003_py39.py
@@ -0,0 +1,19 @@
+from typing import Union
+
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ host: str
+ save_data: bool
+ if_modified_since: Union[str, None] = None
+ traceparent: Union[str, None] = None
+ x_tag: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(headers: CommonHeaders = Header(convert_underscores=False)):
+ return headers
diff --git a/fastapi/__init__.py b/fastapi/__init__.py
index 757b76106..80eb783da 100644
--- a/fastapi/__init__.py
+++ b/fastapi/__init__.py
@@ -1,6 +1,6 @@
"""FastAPI framework, high performance, easy to learn, fast to code, ready for production"""
-__version__ = "0.115.11"
+__version__ = "0.115.12"
from starlette import status as status
diff --git a/fastapi/dependencies/utils.py b/fastapi/dependencies/utils.py
index d205d17fa..84dfa4d03 100644
--- a/fastapi/dependencies/utils.py
+++ b/fastapi/dependencies/utils.py
@@ -750,9 +750,15 @@ def request_params_to_args(
first_field = fields[0]
fields_to_extract = fields
single_not_embedded_field = False
+ default_convert_underscores = True
if len(fields) == 1 and lenient_issubclass(first_field.type_, BaseModel):
fields_to_extract = get_cached_model_fields(first_field.type_)
single_not_embedded_field = True
+ # If headers are in a Pydantic model, the way to disable convert_underscores
+ # would be with Header(convert_underscores=False) at the Pydantic model level
+ default_convert_underscores = getattr(
+ first_field.field_info, "convert_underscores", True
+ )
params_to_process: Dict[str, Any] = {}
@@ -763,7 +769,9 @@ def request_params_to_args(
if isinstance(received_params, Headers):
# Handle fields extracted from a Pydantic Model for a header, each field
# doesn't have a FieldInfo of type Header with the default convert_underscores=True
- convert_underscores = getattr(field.field_info, "convert_underscores", True)
+ convert_underscores = getattr(
+ field.field_info, "convert_underscores", default_convert_underscores
+ )
if convert_underscores:
alias = (
field.alias
diff --git a/fastapi/openapi/utils.py b/fastapi/openapi/utils.py
index bd8f3c106..808646cc2 100644
--- a/fastapi/openapi/utils.py
+++ b/fastapi/openapi/utils.py
@@ -32,6 +32,7 @@ from fastapi.utils import (
generate_operation_id_for_path,
is_body_allowed_for_status_code,
)
+from pydantic import BaseModel
from starlette.responses import JSONResponse
from starlette.routing import BaseRoute
from starlette.status import HTTP_422_UNPROCESSABLE_ENTITY
@@ -113,6 +114,13 @@ def _get_openapi_operation_parameters(
(ParamTypes.header, header_params),
(ParamTypes.cookie, cookie_params),
]
+ default_convert_underscores = True
+ if len(flat_dependant.header_params) == 1:
+ first_field = flat_dependant.header_params[0]
+ if lenient_issubclass(first_field.type_, BaseModel):
+ default_convert_underscores = getattr(
+ first_field.field_info, "convert_underscores", True
+ )
for param_type, param_group in parameter_groups:
for param in param_group:
field_info = param.field_info
@@ -126,8 +134,21 @@ def _get_openapi_operation_parameters(
field_mapping=field_mapping,
separate_input_output_schemas=separate_input_output_schemas,
)
+ name = param.alias
+ convert_underscores = getattr(
+ param.field_info,
+ "convert_underscores",
+ default_convert_underscores,
+ )
+ if (
+ param_type == ParamTypes.header
+ and param.alias == param.name
+ and convert_underscores
+ ):
+ name = param.name.replace("_", "-")
+
parameter = {
- "name": param.alias,
+ "name": name,
"in": param_type.value,
"required": param.required,
"schema": param_schema,
diff --git a/requirements-docs-tests.txt b/requirements-docs-tests.txt
index e7718e61d..71f4a7ab9 100644
--- a/requirements-docs-tests.txt
+++ b/requirements-docs-tests.txt
@@ -1,4 +1,4 @@
# For mkdocstrings and tests
httpx >=0.23.0,<0.28.0
# For linting and generating docs versions
-ruff ==0.9.4
+ruff ==0.11.2
diff --git a/tests/test_tutorial/test_header_param_models/test_tutorial001.py b/tests/test_tutorial/test_header_param_models/test_tutorial001.py
index 06b2404cf..bc876897b 100644
--- a/tests/test_tutorial/test_header_param_models/test_tutorial001.py
+++ b/tests/test_tutorial/test_header_param_models/test_tutorial001.py
@@ -129,13 +129,13 @@ def test_openapi_schema(client: TestClient):
"schema": {"type": "string", "title": "Host"},
},
{
- "name": "save_data",
+ "name": "save-data",
"in": "header",
"required": True,
"schema": {"type": "boolean", "title": "Save Data"},
},
{
- "name": "if_modified_since",
+ "name": "if-modified-since",
"in": "header",
"required": False,
"schema": IsDict(
@@ -171,7 +171,7 @@ def test_openapi_schema(client: TestClient):
),
},
{
- "name": "x_tag",
+ "name": "x-tag",
"in": "header",
"required": False,
"schema": {
diff --git a/tests/test_tutorial/test_header_param_models/test_tutorial002.py b/tests/test_tutorial/test_header_param_models/test_tutorial002.py
index e07655a0c..0615521c4 100644
--- a/tests/test_tutorial/test_header_param_models/test_tutorial002.py
+++ b/tests/test_tutorial/test_header_param_models/test_tutorial002.py
@@ -140,13 +140,13 @@ def test_openapi_schema(client: TestClient):
"schema": {"type": "string", "title": "Host"},
},
{
- "name": "save_data",
+ "name": "save-data",
"in": "header",
"required": True,
"schema": {"type": "boolean", "title": "Save Data"},
},
{
- "name": "if_modified_since",
+ "name": "if-modified-since",
"in": "header",
"required": False,
"schema": IsDict(
@@ -182,7 +182,7 @@ def test_openapi_schema(client: TestClient):
),
},
{
- "name": "x_tag",
+ "name": "x-tag",
"in": "header",
"required": False,
"schema": {
diff --git a/tests/test_tutorial/test_header_param_models/test_tutorial003.py b/tests/test_tutorial/test_header_param_models/test_tutorial003.py
new file mode 100644
index 000000000..60940e1da
--- /dev/null
+++ b/tests/test_tutorial/test_header_param_models/test_tutorial003.py
@@ -0,0 +1,285 @@
+import importlib
+
+import pytest
+from dirty_equals import IsDict
+from fastapi.testclient import TestClient
+from inline_snapshot import snapshot
+
+from tests.utils import needs_py39, needs_py310
+
+
+@pytest.fixture(
+ name="client",
+ params=[
+ "tutorial003",
+ pytest.param("tutorial003_py39", marks=needs_py39),
+ pytest.param("tutorial003_py310", marks=needs_py310),
+ "tutorial003_an",
+ pytest.param("tutorial003_an_py39", marks=needs_py39),
+ pytest.param("tutorial003_an_py310", marks=needs_py310),
+ ],
+)
+def get_client(request: pytest.FixtureRequest):
+ mod = importlib.import_module(f"docs_src.header_param_models.{request.param}")
+
+ client = TestClient(mod.app)
+ return client
+
+
+def test_header_param_model(client: TestClient):
+ response = client.get(
+ "/items/",
+ headers=[
+ ("save_data", "true"),
+ ("if_modified_since", "yesterday"),
+ ("traceparent", "123"),
+ ("x_tag", "one"),
+ ("x_tag", "two"),
+ ],
+ )
+ assert response.status_code == 200
+ assert response.json() == {
+ "host": "testserver",
+ "save_data": True,
+ "if_modified_since": "yesterday",
+ "traceparent": "123",
+ "x_tag": ["one", "two"],
+ }
+
+
+def test_header_param_model_no_underscore(client: TestClient):
+ response = client.get(
+ "/items/",
+ headers=[
+ ("save-data", "true"),
+ ("if-modified-since", "yesterday"),
+ ("traceparent", "123"),
+ ("x-tag", "one"),
+ ("x-tag", "two"),
+ ],
+ )
+ assert response.status_code == 422
+ assert response.json() == snapshot(
+ {
+ "detail": [
+ IsDict(
+ {
+ "type": "missing",
+ "loc": ["header", "save_data"],
+ "msg": "Field required",
+ "input": {
+ "host": "testserver",
+ "traceparent": "123",
+ "x_tag": [],
+ "accept": "*/*",
+ "accept-encoding": "gzip, deflate",
+ "connection": "keep-alive",
+ "user-agent": "testclient",
+ "save-data": "true",
+ "if-modified-since": "yesterday",
+ "x-tag": "two",
+ },
+ }
+ )
+ | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "type": "value_error.missing",
+ "loc": ["header", "save_data"],
+ "msg": "field required",
+ }
+ )
+ ]
+ }
+ )
+
+
+def test_header_param_model_defaults(client: TestClient):
+ response = client.get("/items/", headers=[("save_data", "true")])
+ assert response.status_code == 200
+ assert response.json() == {
+ "host": "testserver",
+ "save_data": True,
+ "if_modified_since": None,
+ "traceparent": None,
+ "x_tag": [],
+ }
+
+
+def test_header_param_model_invalid(client: TestClient):
+ response = client.get("/items/")
+ assert response.status_code == 422
+ assert response.json() == snapshot(
+ {
+ "detail": [
+ IsDict(
+ {
+ "type": "missing",
+ "loc": ["header", "save_data"],
+ "msg": "Field required",
+ "input": {
+ "x_tag": [],
+ "host": "testserver",
+ "accept": "*/*",
+ "accept-encoding": "gzip, deflate",
+ "connection": "keep-alive",
+ "user-agent": "testclient",
+ },
+ }
+ )
+ | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "type": "value_error.missing",
+ "loc": ["header", "save_data"],
+ "msg": "field required",
+ }
+ )
+ ]
+ }
+ )
+
+
+def test_header_param_model_extra(client: TestClient):
+ response = client.get(
+ "/items/", headers=[("save_data", "true"), ("tool", "plumbus")]
+ )
+ assert response.status_code == 200, response.text
+ assert response.json() == snapshot(
+ {
+ "host": "testserver",
+ "save_data": True,
+ "if_modified_since": None,
+ "traceparent": None,
+ "x_tag": [],
+ }
+ )
+
+
+def test_openapi_schema(client: TestClient):
+ response = client.get("/openapi.json")
+ assert response.status_code == 200, response.text
+ assert response.json() == snapshot(
+ {
+ "openapi": "3.1.0",
+ "info": {"title": "FastAPI", "version": "0.1.0"},
+ "paths": {
+ "/items/": {
+ "get": {
+ "summary": "Read Items",
+ "operationId": "read_items_items__get",
+ "parameters": [
+ {
+ "name": "host",
+ "in": "header",
+ "required": True,
+ "schema": {"type": "string", "title": "Host"},
+ },
+ {
+ "name": "save_data",
+ "in": "header",
+ "required": True,
+ "schema": {"type": "boolean", "title": "Save Data"},
+ },
+ {
+ "name": "if_modified_since",
+ "in": "header",
+ "required": False,
+ "schema": IsDict(
+ {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "title": "If Modified Since",
+ }
+ )
+ | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "type": "string",
+ "title": "If Modified Since",
+ }
+ ),
+ },
+ {
+ "name": "traceparent",
+ "in": "header",
+ "required": False,
+ "schema": IsDict(
+ {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "title": "Traceparent",
+ }
+ )
+ | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "type": "string",
+ "title": "Traceparent",
+ }
+ ),
+ },
+ {
+ "name": "x_tag",
+ "in": "header",
+ "required": False,
+ "schema": {
+ "type": "array",
+ "items": {"type": "string"},
+ "default": [],
+ "title": "X Tag",
+ },
+ },
+ ],
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {"application/json": {"schema": {}}},
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ },
+ },
+ }
+ }
+ },
+ "components": {
+ "schemas": {
+ "HTTPValidationError": {
+ "properties": {
+ "detail": {
+ "items": {
+ "$ref": "#/components/schemas/ValidationError"
+ },
+ "type": "array",
+ "title": "Detail",
+ }
+ },
+ "type": "object",
+ "title": "HTTPValidationError",
+ },
+ "ValidationError": {
+ "properties": {
+ "loc": {
+ "items": {
+ "anyOf": [{"type": "string"}, {"type": "integer"}]
+ },
+ "type": "array",
+ "title": "Location",
+ },
+ "msg": {"type": "string", "title": "Message"},
+ "type": {"type": "string", "title": "Error Type"},
+ },
+ "type": "object",
+ "required": ["loc", "msg", "type"],
+ "title": "ValidationError",
+ },
+ }
+ },
+ }
+ )
+