mirror of https://github.com/rjNemo/fastapi synced 2026-06-09 03:56:45 +00:00

Sebastián Ramírez 1f01ce9615

* Updated .py files with Optional tag (up to body_nested_models)

* Update optionals

* docs_src/ all updates, few I was unsure of

* Updated markdown files with Optional param

* es: Add Optional typing to index.md

* Last of markdown files updated with Optional param

* Update highlight lines

* it: Add Optional typings

* README.md: Update with Optional typings

* Update more highlight increments

* Update highlights

* schema-extra-example.md: Update highlights

* updating highlighting on website to reflect .py changes

* Update highlighting for query-params & response-directly

* Address PR comments

* Get rid of unnecessary comment

* ⏪ Revert Optional in Chinese docs as it probably also requires changes in text

* 🎨 Apply format

* ⏪ Revert modified example

* ♻️ Simplify example in docs

* 📝 Update OpenAPI callback example to use Optional

* ✨ Add Optional types to tests

* 📝 Update docs about query params, default to using Optional

* 🎨 Update code examples line highlighting

* 📝 Update nested models docs to use "type parameters" instead of "subtypes"

* 📝 Add notes about FastAPI usage of None

including:

= None

and

= Query(None)

and clarify relationship with Optional[str]

* 📝 Add note about response_model_by_alias

* ♻️ Simplify query param list example

* 🔥 Remove test for removed example

* ✅ Update test for updated example

Co-authored-by: Christopher Nguyen <chrisngyn99@gmail.com>
Co-authored-by: yk396 <yk396@cornell.edu>
Co-authored-by: Kai Chen <kaichen120@gmail.com>

2020-06-28 20:13:30 +02:00

2.9 KiB

Raw Blame History

Header Parameters

You can define Header parameters the same way you define Query, Path and Cookie parameters.

Import `Header`

First import Header:

{!../../../docs_src/header_params/tutorial001.py!}

Declare `Header` parameters

Then declare the header parameters using the same structure as with Path, Query and Cookie.

The first value is the default value, you can pass all the extra validation or annotation parameters:

{!../../../docs_src/header_params/tutorial001.py!}

!!! note "Technical Details" Header is a "sister" class of Path, Query and Cookie. It also inherits from the same common Param class.

But remember that when you import `Query`, `Path`, `Header`, and others from `fastapi`, those are actually functions that return special classes.

!!! info To declare headers, you need to use Header, because otherwise the parameters would be interpreted as query parameters.

Automatic conversion

Header has a little extra functionality on top of what Path, Query and Cookie provide.

Most of the standard headers are separated by a "hyphen" character, also known as the "minus symbol" (-).

But a variable like user-agent is invalid in Python.

So, by default, Header will convert the parameter names characters from underscore (_) to hyphen (-) to extract and document the headers.

Also, HTTP headers are case-insensitive, so, you can declare them with standard Python style (also known as "snake_case").

So, you can use user_agent as you normally would in Python code, instead of needing to capitalize the first letters as User_Agent or something similar.

If for some reason you need to disable automatic conversion of underscores to hyphens, set the parameter convert_underscores of Header to False:

{!../../../docs_src/header_params/tutorial002.py!}

!!! warning Before setting convert_underscores to False, bear in mind that some HTTP proxies and servers disallow the usage of headers with underscores.

Duplicate headers

It is possible to receive duplicate headers. That means, the same header with multiple values.

You can define those cases using a list in the type declaration.

You will receive all the values from the duplicate header as a Python list.

For example, to declare a header of X-Token that can appear more than once, you can write:

{!../../../docs_src/header_params/tutorial003.py!}

If you communicate with that path operation sending two HTTP headers like:

X-Token: foo
X-Token: bar

The response would be like:

{
    "X-Token values": [
        "bar",
        "foo"
    ]
}

Recap

Declare headers with Header, using the same common pattern as Query, Path and Cookie.

And don't worry about underscores in your variables, FastAPI will take care of converting them.

2.9 KiB Raw Blame History