From a021cf9c8fb99e84de97af573588007080cf727c Mon Sep 17 00:00:00 2001 From: TabarakoAkula Date: Thu, 15 Jun 2023 21:18:02 +0300 Subject: [PATCH 1/7] Add Russian translation for docs/ru/docs/tutorial/metadata.md --- docs/ru/docs/tutorial/metadata.md | 111 ++++++++++++++++++++++++++++++ docs/ru/mkdocs.yml | 1 + 2 files changed, 112 insertions(+) create mode 100644 docs/ru/docs/tutorial/metadata.md diff --git a/docs/ru/docs/tutorial/metadata.md b/docs/ru/docs/tutorial/metadata.md new file mode 100644 index 0000000000000..b0479ab8dfb2f --- /dev/null +++ b/docs/ru/docs/tutorial/metadata.md @@ -0,0 +1,111 @@ +# URL-адреса метаданных и документации + +Вы можете настроить несколько конфигураций метаданных в вашем **FastAPI** приложении. + +## Метаданные для API + +Вы можете задать следующие поля, которые используются в спецификации OpenAPI и в UIs автоматической документации API: + +| Параметр | Тип | Описание | +|------------|--|-------------| +| `title` | `str` | Заголовок API. | +| `description` | `str` | Краткое описание API. Может быть использован Markdown. | +| `version` | `string` | Версия API. Версия вашего собственного приложения, а не OpenAPI. К примеру `2.5.0`. | +| `terms_of_service` | `str` | Ссылка к условиям пользования API. Если указано, то это должен быть URL-адрес. | +| `contact` | `dict` | Контактная информация для открытого API. Может содержать несколько полей.
поля contact
ПараметрТипОписание
namestrИдентификационное имя контактного лица/организации.
urlstrURL указывающий на контактную информацию. ДОЛЖЕН быть в формате URL.
emailstrEmail адрес контактного лица/организации. ДОЛЖЕН быть в формате email адреса.
| +| `license_info` | `dict` | Информация о лицензии открытого API. Может содержать несколько полей.
поля license_info
ПараметрТипОписание
namestrОБЯЗАТЕЛЬНО (если license_info это множество). Имя лицензии, используемой для API
urlstrURL, указывающий на лицензию, используемую для API. ДОЛЖЕН быть в формате URL.
| + +Вы можете задать их следующим образом: + +```Python hl_lines="3-16 19-31" +{!../../../docs_src/metadata/tutorial001.py!} +``` + +!!! tip "Подсказка" + Вы можете использовать Markdown в поле `description` и оно будет отображено в выводе. + +С этой конфигурацией, автоматическая документация API будут выглядеть так: + + + +## Метаданные для тегов + +Вы также можете добавить дополнительные метаданные для различных тегов, используемых, что бы сгруппировать ваши операции пути с параметром `openapi_tags`. + +Они берут список, содержащий один словарь для каждого тега. + +Каждый словарь может содержать в себе: + +* `name` (**обязательно**): `str` - значение с тем же именем тега, которое вы используете в параметре `tags` в ваших *операциях пути* и `APIRouter`ах. +* `description`: `str` - значение с кратким описанием для тега. Может включать в себя Markdown и будет показан в UI документации. +* `externalDocs`: `dict` - значение описывающее внешнюю документацию. Включает в себя: + * `description`: `str` - значение с кратким описанием для внешней документации. + * `url` (**обязательно**): `str` - значение с URL-адресом для внешней документации. + +### Создание метаданных для тегов + +Давайте попробуем сделать это на примере с тегами для `users` и `items`. + +Создайте метаданные для ваших тегов и передайте их в параметре `openapi_tags`: + +```Python hl_lines="3-16 18" +{!../../../docs_src/metadata/tutorial004.py!} +``` + +Помните, что вы можете использовать Markdown внутри описания, к примеру "login" будет отображен жирным шрифтом (**login**) и "fancy" будет отображаться курсивом (_fancy_). + +!!! tip "Подсказка" + Вам необязательно добавлять метаданные для всех используемых тегов + +### Используйте собственные теги +Используйте параметр `tags` с вашими *операциями пути* (и `APIRouter`ами) что бы присвоить им различные теги: + +```Python hl_lines="21 26" +{!../../../docs_src/metadata/tutorial004.py!} +``` + +!!! info "Дополнительная информация" + Узнайте больше о тегах в [Path Operation Configuration](../path-operation-configuration/#tags){.internal-link target=_blank}. + +### Проверьте документацию + +Теперь, если вы проверите документацию, вы увидите всю дополнительную информацию: + + + +### Порядок расположения тегов + +Порядок расположения каждого тега словаря метаданных также определяет порядок, отображаемый в документах UI + +К примеру, несмотря на то, что `users` будут идти после `items` в алфавитном порядке, они показываются перед ним, потому что мы добавляем свои метаданные в качестве первого словаря в списке. + +## URL-адреса OpenAPI + +По умолчанию схема OpenAPI отображена в `/openapi.json`. + +Но вы можете изменить её с помощью параметра `openapi_url`. + +К примеру, что бы задать её отображение в `/api/v1/openapi.json`: + +```Python hl_lines="3" +{!../../../docs_src/metadata/tutorial002.py!} +``` + +Если вы хотите отключить схему OpenAPI полностью, вы можете задать `openapi_url=None`, это также отключит пользовательские интерфейсы документации, которые его использует. + +## URL-адреса документации + +Вы можете изменить конфигурацию двух пользовательских интерфейсов документации, включающие + +* **Swagger UI**: отображаемый в `/docs`. + * Вы можете задать его URL с помощью параметра `docs_url`. + * Вы можете отключить это с помощью настройки `docs_url=None`. +* **ReDoc**: отображаемый в `/redoc`. + * Вы можете задать его URL с помощью параметра `redoc_url`. + * Вы можете отключить это с помощью настройки `redoc_url=None`. + +К примеру, что бы задать Swagger UI отображаемый в `/documentation` и отключить ReDoc: + +```Python hl_lines="3" +{!../../../docs_src/metadata/tutorial003.py!} +``` diff --git a/docs/ru/mkdocs.yml b/docs/ru/mkdocs.yml index 9fb56ce1bb975..6c7fad3709276 100644 --- a/docs/ru/mkdocs.yml +++ b/docs/ru/mkdocs.yml @@ -80,6 +80,7 @@ nav: - tutorial/response-status-code.md - tutorial/query-params.md - tutorial/body-multiple-params.md + - tutorial/metadata.md - tutorial/static-files.md - tutorial/debugging.md - tutorial/schema-extra-example.md From 09294e8171f7b00894bb5200d78496cafda42386 Mon Sep 17 00:00:00 2001 From: TabarakoAkula Date: Sat, 17 Jun 2023 16:50:18 +0300 Subject: [PATCH 2/7] Add Russian translation for docs/ru/docs/tutorial/path-operation-configuration.md --- .../tutorial/path-operation-configuration.md | 179 ++++++++++++++++++ docs/ru/mkdocs.yml | 1 + 2 files changed, 180 insertions(+) create mode 100644 docs/ru/docs/tutorial/path-operation-configuration.md diff --git a/docs/ru/docs/tutorial/path-operation-configuration.md b/docs/ru/docs/tutorial/path-operation-configuration.md new file mode 100644 index 0000000000000..78dc1ce9770eb --- /dev/null +++ b/docs/ru/docs/tutorial/path-operation-configuration.md @@ -0,0 +1,179 @@ +# Конфигурация операций пути + +Существует несколько параметров, которые вы можете передать вашему *декоратору операций пути* для его настройки. + +!!! 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.6+" + + ```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`-значениями (обычно только `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.6+" + + ```Python hl_lines="17 22 27" + {!> ../../../docs_src/path_operation_configuration/tutorial002.py!} + ``` + +Они будут добавлены в схему OpenAPI и будут использованы в автоматической документации интерфейса: + + + +### Теги с наборами + +Если у вас большое приложение, под конец вы можете набрать **несколько тегов**, и вы можете хотеть убедиться в том, что всегда используете **один и тот же тег** для связанных *операций пути*. + +В этих случаях, имеет смысл хранить теги в `Enum`. + +**FastAPI** поддерживает это также, как и с обычными строками: + +```Python hl_lines="1 8-10 13 18" +{!../../../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.6+" + + ```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.6+" + + ```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.6+" + + ```Python hl_lines="21" + {!> ../../../docs_src/path_operation_configuration/tutorial005.py!} + ``` + +!!! info "Дополнительная информация" + Помните, что `response_description` относится конкретно к ответу, а `description` в основном относится к *операциям пути*. + +!!! check "Технические детали" + OpenAPI указывает, что каждой *операции пути* необходимо описание ответа. + + Если вдруг вы не укажите одно из них, то **FastAPI** автоматически сгенерирует один из "Удачных ответов". + + + +## Устаревшие *операции пути* + +Если вам необходимо пометить *операцию пути* как устаревшую, но без её удаления, передайте параметр `deprecated`: + +```Python hl_lines="16" +{!../../../docs_src/path_operation_configuration/tutorial006.py!} +``` + +Он будет четко помечен как устаревший в интерактивной документации: + + + +Проверьте, как устаревшие и не-устаревшие *операции пути* будут выглядеть: + + + +## Итог + +Вы можете легко конфигурировать и добавлять метаданные в ваши *операции пути*, передавая параметры *декораторам операций пути*. diff --git a/docs/ru/mkdocs.yml b/docs/ru/mkdocs.yml index 6c7fad3709276..aee4b8154c32a 100644 --- a/docs/ru/mkdocs.yml +++ b/docs/ru/mkdocs.yml @@ -81,6 +81,7 @@ nav: - tutorial/query-params.md - tutorial/body-multiple-params.md - tutorial/metadata.md + - tutorial/path-operation-configuration.md - tutorial/static-files.md - tutorial/debugging.md - tutorial/schema-extra-example.md From 7f2ab1a058e73ded06848ab670af43a316ce3f00 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sat, 17 Jun 2023 13:55:18 +0000 Subject: [PATCH 3/7] =?UTF-8?q?=F0=9F=8E=A8=20[pre-commit.ci]=20Auto=20for?= =?UTF-8?q?mat=20from=20pre-commit.com=20hooks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/ru/docs/tutorial/metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ru/docs/tutorial/metadata.md b/docs/ru/docs/tutorial/metadata.md index b0479ab8dfb2f..ebeb2e6239a3e 100644 --- a/docs/ru/docs/tutorial/metadata.md +++ b/docs/ru/docs/tutorial/metadata.md @@ -55,7 +55,7 @@ Помните, что вы можете использовать Markdown внутри описания, к примеру "login" будет отображен жирным шрифтом (**login**) и "fancy" будет отображаться курсивом (_fancy_). !!! tip "Подсказка" - Вам необязательно добавлять метаданные для всех используемых тегов + Вам необязательно добавлять метаданные для всех используемых тегов ### Используйте собственные теги Используйте параметр `tags` с вашими *операциями пути* (и `APIRouter`ами) что бы присвоить им различные теги: From 53e1bd66c20e95390f93409b090f553fd82a00f9 Mon Sep 17 00:00:00 2001 From: TabarakoAkula Date: Sat, 17 Jun 2023 21:22:15 +0300 Subject: [PATCH 4/7] Add Russian translation for docs/ru/docs/tutorial/path-operation-configuration.md --- .../ru/docs/tutorial/path-operation-configuration.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/ru/docs/tutorial/path-operation-configuration.md b/docs/ru/docs/tutorial/path-operation-configuration.md index 78dc1ce9770eb..3604e3bcf3181 100644 --- a/docs/ru/docs/tutorial/path-operation-configuration.md +++ b/docs/ru/docs/tutorial/path-operation-configuration.md @@ -38,9 +38,9 @@ **FastAPI** предоставляет тот же `starlette.status`, что и `fastapi.status` для удобства разработчкиа. Но идет он непросредственно от Starlette. -## Теги с наборами +## Теги -Вы можете добавлять теги к вашим *операциям пути*, добавив параметр `tags` с `list` заполненным `str`-значениями (обычно только `str`-значения): +Вы можете добавлять теги к вашим *операциям пути*, добавив параметр `tags` с `list` заполненным `str`-значениями (обычно в нём только одна строка): === "Python 3.10+" @@ -64,7 +64,7 @@ -### Теги с наборами +### Теги с перечислениями Если у вас большое приложение, под конец вы можете набрать **несколько тегов**, и вы можете хотеть убедиться в том, что всегда используете **один и тот же тег** для связанных *операций пути*. @@ -76,7 +76,7 @@ {!../../../docs_src/path_operation_configuration/tutorial002b.py!} ``` -## Краткое содержание и описание +## Краткое и развёрнутое содержание Вы можете добавить `summary` и `description`: @@ -158,7 +158,7 @@ -## Устаревшие *операции пути* +## Обозначение *операции пути* как устаревшей Если вам необходимо пометить *операцию пути* как устаревшую, но без её удаления, передайте параметр `deprecated`: @@ -174,6 +174,6 @@ -## Итог +## Резюме Вы можете легко конфигурировать и добавлять метаданные в ваши *операции пути*, передавая параметры *декораторам операций пути*. From 57e7fd93c1bbf3fffd3cd872c5e77306ce1eb451 Mon Sep 17 00:00:00 2001 From: TabarakoAkula <113298631+TabarakoAkula@users.noreply.github.com> Date: Sat, 17 Jun 2023 21:30:53 +0300 Subject: [PATCH 5/7] Delete metadata.md --- docs/ru/docs/tutorial/metadata.md | 111 ------------------------------ 1 file changed, 111 deletions(-) delete mode 100644 docs/ru/docs/tutorial/metadata.md diff --git a/docs/ru/docs/tutorial/metadata.md b/docs/ru/docs/tutorial/metadata.md deleted file mode 100644 index ebeb2e6239a3e..0000000000000 --- a/docs/ru/docs/tutorial/metadata.md +++ /dev/null @@ -1,111 +0,0 @@ -# URL-адреса метаданных и документации - -Вы можете настроить несколько конфигураций метаданных в вашем **FastAPI** приложении. - -## Метаданные для API - -Вы можете задать следующие поля, которые используются в спецификации OpenAPI и в UIs автоматической документации API: - -| Параметр | Тип | Описание | -|------------|--|-------------| -| `title` | `str` | Заголовок API. | -| `description` | `str` | Краткое описание API. Может быть использован Markdown. | -| `version` | `string` | Версия API. Версия вашего собственного приложения, а не OpenAPI. К примеру `2.5.0`. | -| `terms_of_service` | `str` | Ссылка к условиям пользования API. Если указано, то это должен быть URL-адрес. | -| `contact` | `dict` | Контактная информация для открытого API. Может содержать несколько полей.
поля contact
ПараметрТипОписание
namestrИдентификационное имя контактного лица/организации.
urlstrURL указывающий на контактную информацию. ДОЛЖЕН быть в формате URL.
emailstrEmail адрес контактного лица/организации. ДОЛЖЕН быть в формате email адреса.
| -| `license_info` | `dict` | Информация о лицензии открытого API. Может содержать несколько полей.
поля license_info
ПараметрТипОписание
namestrОБЯЗАТЕЛЬНО (если license_info это множество). Имя лицензии, используемой для API
urlstrURL, указывающий на лицензию, используемую для API. ДОЛЖЕН быть в формате URL.
| - -Вы можете задать их следующим образом: - -```Python hl_lines="3-16 19-31" -{!../../../docs_src/metadata/tutorial001.py!} -``` - -!!! tip "Подсказка" - Вы можете использовать Markdown в поле `description` и оно будет отображено в выводе. - -С этой конфигурацией, автоматическая документация API будут выглядеть так: - - - -## Метаданные для тегов - -Вы также можете добавить дополнительные метаданные для различных тегов, используемых, что бы сгруппировать ваши операции пути с параметром `openapi_tags`. - -Они берут список, содержащий один словарь для каждого тега. - -Каждый словарь может содержать в себе: - -* `name` (**обязательно**): `str` - значение с тем же именем тега, которое вы используете в параметре `tags` в ваших *операциях пути* и `APIRouter`ах. -* `description`: `str` - значение с кратким описанием для тега. Может включать в себя Markdown и будет показан в UI документации. -* `externalDocs`: `dict` - значение описывающее внешнюю документацию. Включает в себя: - * `description`: `str` - значение с кратким описанием для внешней документации. - * `url` (**обязательно**): `str` - значение с URL-адресом для внешней документации. - -### Создание метаданных для тегов - -Давайте попробуем сделать это на примере с тегами для `users` и `items`. - -Создайте метаданные для ваших тегов и передайте их в параметре `openapi_tags`: - -```Python hl_lines="3-16 18" -{!../../../docs_src/metadata/tutorial004.py!} -``` - -Помните, что вы можете использовать Markdown внутри описания, к примеру "login" будет отображен жирным шрифтом (**login**) и "fancy" будет отображаться курсивом (_fancy_). - -!!! tip "Подсказка" - Вам необязательно добавлять метаданные для всех используемых тегов - -### Используйте собственные теги -Используйте параметр `tags` с вашими *операциями пути* (и `APIRouter`ами) что бы присвоить им различные теги: - -```Python hl_lines="21 26" -{!../../../docs_src/metadata/tutorial004.py!} -``` - -!!! info "Дополнительная информация" - Узнайте больше о тегах в [Path Operation Configuration](../path-operation-configuration/#tags){.internal-link target=_blank}. - -### Проверьте документацию - -Теперь, если вы проверите документацию, вы увидите всю дополнительную информацию: - - - -### Порядок расположения тегов - -Порядок расположения каждого тега словаря метаданных также определяет порядок, отображаемый в документах UI - -К примеру, несмотря на то, что `users` будут идти после `items` в алфавитном порядке, они показываются перед ним, потому что мы добавляем свои метаданные в качестве первого словаря в списке. - -## URL-адреса OpenAPI - -По умолчанию схема OpenAPI отображена в `/openapi.json`. - -Но вы можете изменить её с помощью параметра `openapi_url`. - -К примеру, что бы задать её отображение в `/api/v1/openapi.json`: - -```Python hl_lines="3" -{!../../../docs_src/metadata/tutorial002.py!} -``` - -Если вы хотите отключить схему OpenAPI полностью, вы можете задать `openapi_url=None`, это также отключит пользовательские интерфейсы документации, которые его использует. - -## URL-адреса документации - -Вы можете изменить конфигурацию двух пользовательских интерфейсов документации, включающие - -* **Swagger UI**: отображаемый в `/docs`. - * Вы можете задать его URL с помощью параметра `docs_url`. - * Вы можете отключить это с помощью настройки `docs_url=None`. -* **ReDoc**: отображаемый в `/redoc`. - * Вы можете задать его URL с помощью параметра `redoc_url`. - * Вы можете отключить это с помощью настройки `redoc_url=None`. - -К примеру, что бы задать Swagger UI отображаемый в `/documentation` и отключить ReDoc: - -```Python hl_lines="3" -{!../../../docs_src/metadata/tutorial003.py!} -``` From 02497fd16439aaecd566388f0e48b3f83f0e6711 Mon Sep 17 00:00:00 2001 From: TabarakoAkula <113298631+TabarakoAkula@users.noreply.github.com> Date: Sat, 17 Jun 2023 21:34:17 +0300 Subject: [PATCH 6/7] Update mkdocs.yml --- docs/ru/mkdocs.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/ru/mkdocs.yml b/docs/ru/mkdocs.yml index aee4b8154c32a..00e28c3e631aa 100644 --- a/docs/ru/mkdocs.yml +++ b/docs/ru/mkdocs.yml @@ -80,7 +80,6 @@ nav: - tutorial/response-status-code.md - tutorial/query-params.md - tutorial/body-multiple-params.md - - tutorial/metadata.md - tutorial/path-operation-configuration.md - tutorial/static-files.md - tutorial/debugging.md From 13d2845152eab38d2e543506b0ca8bdc351fd209 Mon Sep 17 00:00:00 2001 From: TabarakoAkula <113298631+TabarakoAkula@users.noreply.github.com> Date: Tue, 20 Jun 2023 12:40:45 +0300 Subject: [PATCH 7/7] Apply suggestions from code review Co-authored-by: ivan-abc <36765187+ivan-abc@users.noreply.github.com> Co-authored-by: Alexandr --- .../tutorial/path-operation-configuration.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/ru/docs/tutorial/path-operation-configuration.md b/docs/ru/docs/tutorial/path-operation-configuration.md index 3604e3bcf3181..013903add1cc0 100644 --- a/docs/ru/docs/tutorial/path-operation-configuration.md +++ b/docs/ru/docs/tutorial/path-operation-configuration.md @@ -31,12 +31,12 @@ {!> ../../../docs_src/path_operation_configuration/tutorial001.py!} ``` -Этот код состояния будет использован в ответе, и будет добавлен в схему OpenAPI. +Этот код состояния будет использован в ответе и будет добавлен в схему OpenAPI. !!! note "Технические детали" Вы также можете использовать `from starlette import status`. - **FastAPI** предоставляет тот же `starlette.status`, что и `fastapi.status` для удобства разработчкиа. Но идет он непросредственно от Starlette. + **FastAPI** предоставляет тот же `starlette.status` под псевдонимом `fastapi.status` для удобства разработчика. Но его источник - это непосредственно Starlette. ## Теги @@ -66,11 +66,11 @@ ### Теги с перечислениями -Если у вас большое приложение, под конец вы можете набрать **несколько тегов**, и вы можете хотеть убедиться в том, что всегда используете **один и тот же тег** для связанных *операций пути*. +Если у вас большое приложение, вы можете прийти к необходимости добавить **несколько тегов**, и возможно, вы захотите убедиться в том, что всегда используете **один и тот же тег** для связанных *операций пути*. -В этих случаях, имеет смысл хранить теги в `Enum`. +В этих случаях, имеет смысл хранить теги в классе `Enum`. -**FastAPI** поддерживает это также, как и с обычными строками: +**FastAPI** поддерживает это так же, как и в случае с обычными строками: ```Python hl_lines="1 8-10 13 18" {!../../../docs_src/path_operation_configuration/tutorial002b.py!} @@ -78,7 +78,7 @@ ## Краткое и развёрнутое содержание -Вы можете добавить `summary` и `description`: +Вы можете добавить параметры `summary` и `description`: === "Python 3.10+" @@ -100,9 +100,9 @@ ## Описание из строк документации -Так как описания обычно длинные и содержат много строк, вы можете объявить описание *операции пути* в функции строки документации и **FastAPI** прочитает её отсюда. +Так как описания обычно длинные и содержат много строк, вы можете объявить описание *операции пути* в функции строки документации и **FastAPI** прочитает её отсюда. -Вы можете использовать Markdown в строке документации, и оно будет интерпретировано и отображено корректно (с учетом отступа в строке документации). +Вы можете использовать Markdown в строке документации, и он будет интерпретирован и отображён корректно (с учетом отступа в строке документации). === "Python 3.10+" @@ -149,18 +149,18 @@ ``` !!! info "Дополнительная информация" - Помните, что `response_description` относится конкретно к ответу, а `description` в основном относится к *операциям пути*. + Помните, что `response_description` относится конкретно к ответу, а `description` относится к *операции пути* в целом. !!! check "Технические детали" OpenAPI указывает, что каждой *операции пути* необходимо описание ответа. - Если вдруг вы не укажите одно из них, то **FastAPI** автоматически сгенерирует один из "Удачных ответов". + Если вдруг вы не укажете его, то **FastAPI** автоматически сгенерирует это описание с текстом "Successful response". ## Обозначение *операции пути* как устаревшей -Если вам необходимо пометить *операцию пути* как устаревшую, но без её удаления, передайте параметр `deprecated`: +Если вам необходимо пометить *операцию пути* как устаревшую, при этом не удаляя её, передайте параметр `deprecated`: ```Python hl_lines="16" {!../../../docs_src/path_operation_configuration/tutorial006.py!} @@ -170,7 +170,7 @@ -Проверьте, как устаревшие и не-устаревшие *операции пути* будут выглядеть: +Проверьте, как будут выглядеть устаревшие и не устаревшие *операции пути*: