2ba7586ff3
* 📝 Update docs, require Python 3.8+, drop 3.7 * 🔧 Update pyproject.toml, drop support for Python 3.7, require Python 3.8+ * 👷 Update CI GitHub Actions, drop support for Python 3.7, require 3.8+ * 📝 Update docs' references to Python 3.6 and 3.7, use Python 3.8
8.0 KiB
Конфигурация операций пути
Существует несколько параметров, которые вы можете передать вашему декоратору операций пути для его настройки.
!!! warning "Внимание" Помните, что эти параметры передаются непосредственно декоратору операций пути, а не вашей функции-обработчику операций пути.
Коды состояния
Вы можете определить (HTTP) status_code, который будет использован в ответах вашей операции пути.
Вы можете передать только int-значение кода, например 404.
Но если вы не помните, для чего нужен каждый числовой код, вы можете использовать сокращенные константы в параметре status:
=== "Python 3.10+"
```Python hl_lines="1 15"
{!> ../../../docs_src/path_operation_configuration/tutorial001_py310.py!}
```
=== "Python 3.9+"
```Python hl_lines="3 17"
{!> ../../../docs_src/path_operation_configuration/tutorial001_py39.py!}
```
=== "Python 3.8+"
```Python hl_lines="3 17"
{!> ../../../docs_src/path_operation_configuration/tutorial001.py!}
```
Этот код состояния будет использован в ответе и будет добавлен в схему OpenAPI.
!!! note "Технические детали"
Вы также можете использовать from starlette import status.
**FastAPI** предоставляет тот же `starlette.status` под псевдонимом `fastapi.status` для удобства разработчика. Но его источник - это непосредственно Starlette.
Теги
Вы можете добавлять теги к вашим операциям пути, добавив параметр tags с list заполненным str-значениями (обычно в нём только одна строка):
=== "Python 3.10+"
```Python hl_lines="15 20 25"
{!> ../../../docs_src/path_operation_configuration/tutorial002_py310.py!}
```
=== "Python 3.9+"
```Python hl_lines="17 22 27"
{!> ../../../docs_src/path_operation_configuration/tutorial002_py39.py!}
```
=== "Python 3.8+"
```Python hl_lines="17 22 27"
{!> ../../../docs_src/path_operation_configuration/tutorial002.py!}
```
Они будут добавлены в схему OpenAPI и будут использованы в автоматической документации интерфейса:
Теги с перечислениями
Если у вас большое приложение, вы можете прийти к необходимости добавить несколько тегов, и возможно, вы захотите убедиться в том, что всегда используете один и тот же тег для связанных операций пути.
В этих случаях, имеет смысл хранить теги в классе Enum.
FastAPI поддерживает это так же, как и в случае с обычными строками:
{!../../../docs_src/path_operation_configuration/tutorial002b.py!}
Краткое и развёрнутое содержание
Вы можете добавить параметры summary и description:
=== "Python 3.10+"
```Python hl_lines="18-19"
{!> ../../../docs_src/path_operation_configuration/tutorial003_py310.py!}
```
=== "Python 3.9+"
```Python hl_lines="20-21"
{!> ../../../docs_src/path_operation_configuration/tutorial003_py39.py!}
```
=== "Python 3.8+"
```Python hl_lines="20-21"
{!> ../../../docs_src/path_operation_configuration/tutorial003.py!}
```
Описание из строк документации
Так как описания обычно длинные и содержат много строк, вы можете объявить описание операции пути в функции строки документации и FastAPI прочитает её отсюда.
Вы можете использовать Markdown в строке документации, и он будет интерпретирован и отображён корректно (с учетом отступа в строке документации).
=== "Python 3.10+"
```Python hl_lines="17-25"
{!> ../../../docs_src/path_operation_configuration/tutorial004_py310.py!}
```
=== "Python 3.9+"
```Python hl_lines="19-27"
{!> ../../../docs_src/path_operation_configuration/tutorial004_py39.py!}
```
=== "Python 3.8+"
```Python hl_lines="19-27"
{!> ../../../docs_src/path_operation_configuration/tutorial004.py!}
```
Он будет использован в интерактивной документации:
Описание ответа
Вы можете указать описание ответа с помощью параметра response_description:
=== "Python 3.10+"
```Python hl_lines="19"
{!> ../../../docs_src/path_operation_configuration/tutorial005_py310.py!}
```
=== "Python 3.9+"
```Python hl_lines="21"
{!> ../../../docs_src/path_operation_configuration/tutorial005_py39.py!}
```
=== "Python 3.8+"
```Python hl_lines="21"
{!> ../../../docs_src/path_operation_configuration/tutorial005.py!}
```
!!! info "Дополнительная информация"
Помните, что response_description относится конкретно к ответу, а description относится к операции пути в целом.
!!! check "Технические детали" OpenAPI указывает, что каждой операции пути необходимо описание ответа.
Если вдруг вы не укажете его, то **FastAPI** автоматически сгенерирует это описание с текстом "Successful response".
Обозначение операции пути как устаревшей
Если вам необходимо пометить операцию пути как устаревшую, при этом не удаляя её, передайте параметр deprecated:
{!../../../docs_src/path_operation_configuration/tutorial006.py!}
Он будет четко помечен как устаревший в интерактивной документации:
Проверьте, как будут выглядеть устаревшие и не устаревшие операции пути:
Резюме
Вы можете легко конфигурировать и добавлять метаданные в ваши операции пути, передавая параметры декораторам операций пути.