mirror of https://github.com/tiangolo/fastapi.git
🌐 Add Russian translation for `docs/ru/docs/tutorial/first-steps.md` (#9471)
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Vladislav Kramorenko <85196001+Xewus@users.noreply.github.com> Co-authored-by: Sebastián Ramírez <tiangolo@gmail.com>
This commit is contained in:
Artem Golicyn
GitHub
parent
4c9ac66554
commit
918d96f6ad
|
|
@ -0,0 +1,333 @@
|
|||
# Первые шаги
|
||||
|
||||
Самый простой FastAPI файл может выглядеть так:
|
||||
|
||||
```Python
|
||||
{!../../../docs_src/first_steps/tutorial001.py!}
|
||||
```
|
||||
|
||||
Скопируйте в файл `main.py`.
|
||||
|
||||
Запустите сервер в режиме реального времени:
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ uvicorn main:app --reload
|
||||
|
||||
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
|
||||
<span style="color: green;">INFO</span>: Started reloader process [28720]
|
||||
<span style="color: green;">INFO</span>: Started server process [28722]
|
||||
<span style="color: green;">INFO</span>: Waiting for application startup.
|
||||
<span style="color: green;">INFO</span>: Application startup complete.
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
!!! note "Технические детали"
|
||||
Команда `uvicorn main:app` обращается к:
|
||||
|
||||
* `main`: файл `main.py` (модуль Python).
|
||||
* `app`: объект, созданный внутри файла `main.py` в строке `app = FastAPI()`.
|
||||
* `--reload`: перезапускает сервер после изменения кода. Используйте только для разработки.
|
||||
|
||||
В окне вывода появится следующая строка:
|
||||
|
||||
```hl_lines="4"
|
||||
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
|
||||
```
|
||||
|
||||
Эта строка показывает URL-адрес, по которому приложение доступно на локальной машине.
|
||||
|
||||
### Проверьте
|
||||
|
||||
Откройте браузер по адресу: <a href="http://127.0.0.1:8000" class="external-link" target="_blank">http://127.0.0.1:8000</a>.
|
||||
|
||||
Вы увидите JSON-ответ следующего вида:
|
||||
|
||||
```JSON
|
||||
{"message": "Hello World"}
|
||||
```
|
||||
|
||||
### Интерактивная документация API
|
||||
|
||||
Перейдите по адресу: <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>.
|
||||
|
||||
Вы увидите автоматически сгенерированную, интерактивную документацию по API (предоставленную <a href="https://github.com/swagger-api/swagger-ui" class="external-link" target="_blank">Swagger UI</a>):
|
||||
|
||||
|
||||
|
||||
### Альтернативная документация API
|
||||
|
||||
Теперь перейдите по адресу <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>.
|
||||
|
||||
Вы увидите альтернативную автоматически сгенерированную документацию (предоставленную <a href="https://github.com/Rebilly/ReDoc" class="external-link" target="_blank">ReDoc</a>):
|
||||
|
||||
|
||||
|
||||
### OpenAPI
|
||||
|
||||
**FastAPI** генерирует "схему" всего API, используя стандарт **OpenAPI**.
|
||||
|
||||
#### "Схема"
|
||||
|
||||
"Схема" - это определение или описание чего-либо. Не код, реализующий это, а только абстрактное описание.
|
||||
|
||||
#### API "схема"
|
||||
|
||||
<a href="https://github.com/OAI/OpenAPI-Specification" class="external-link" target="_blank">OpenAPI</a> - это спецификация, которая определяет, как описывать схему API.
|
||||
|
||||
Определение схемы содержит пути (paths) API, их параметры и т.п.
|
||||
|
||||
#### "Схема" данных
|
||||
|
||||
Термин "схема" также может относиться к формату или структуре некоторых данных, например, JSON.
|
||||
|
||||
Тогда, подразумеваются атрибуты JSON, их типы данных и т.п.
|
||||
|
||||
#### OpenAPI и JSON Schema
|
||||
|
||||
OpenAPI описывает схему API. Эта схема содержит определения (или "схемы") данных, отправляемых и получаемых API. Для описания структуры данных в JSON используется стандарт **JSON Schema**.
|
||||
|
||||
#### Рассмотрим `openapi.json`
|
||||
|
||||
Если Вас интересует, как выглядит исходная схема OpenAPI, то FastAPI автоматически генерирует JSON-схему со всеми описаниями API.
|
||||
|
||||
Можете посмотреть здесь: <a href="http://127.0.0.1:8000/openapi.json" class="external-link" target="_blank">http://127.0.0.1:8000/openapi.json</a>.
|
||||
|
||||
Вы увидите примерно такой JSON:
|
||||
|
||||
```JSON
|
||||
{
|
||||
"openapi": "3.0.2",
|
||||
"info": {
|
||||
"title": "FastAPI",
|
||||
"version": "0.1.0"
|
||||
},
|
||||
"paths": {
|
||||
"/items/": {
|
||||
"get": {
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Successful Response",
|
||||
"content": {
|
||||
"application/json": {
|
||||
|
||||
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
#### Для чего нужен OpenAPI
|
||||
|
||||
Схема OpenAPI является основой для обеих систем интерактивной документации.
|
||||
|
||||
Существуют десятки альтернативных инструментов, основанных на OpenAPI. Вы можете легко добавить любой из них к **FastAPI** приложению.
|
||||
|
||||
Вы также можете использовать OpenAPI для автоматической генерации кода для клиентов, которые взаимодействуют с API. Например, для фронтенд-, мобильных или IoT-приложений.
|
||||
|
||||
## Рассмотрим поэтапно
|
||||
|
||||
### Шаг 1: импортируйте `FastAPI`
|
||||
|
||||
```Python hl_lines="1"
|
||||
{!../../../docs_src/first_steps/tutorial001.py!}
|
||||
```
|
||||
|
||||
`FastAPI` это класс в Python, который предоставляет всю функциональность для API.
|
||||
|
||||
!!! note "Технические детали"
|
||||
`FastAPI` это класс, который наследуется непосредственно от `Starlette`.
|
||||
|
||||
Вы можете использовать всю функциональность <a href="https://www.starlette.io/" class="external-link" target="_blank">Starlette</a> в `FastAPI`.
|
||||
|
||||
### Шаг 2: создайте экземпляр `FastAPI`
|
||||
|
||||
```Python hl_lines="3"
|
||||
{!../../../docs_src/first_steps/tutorial001.py!}
|
||||
```
|
||||
|
||||
Переменная `app` является экземпляром класса `FastAPI`.
|
||||
|
||||
Это единая точка входа для создания и взаимодействия с API.
|
||||
|
||||
Именно к этой переменной `app` обращается `uvicorn` в команде:
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ uvicorn main:app --reload
|
||||
|
||||
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
Если создать такое приложение:
|
||||
|
||||
```Python hl_lines="3"
|
||||
{!../../../docs_src/first_steps/tutorial002.py!}
|
||||
```
|
||||
|
||||
И поместить его в `main.py`, тогда вызов `uvicorn` будет таким:
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ uvicorn main:my_awesome_api --reload
|
||||
|
||||
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
### Шаг 3: определите *операцию пути (path operation)*
|
||||
|
||||
#### Путь (path)
|
||||
|
||||
"Путь" это часть URL, после первого символа `/`, следующего за именем домена.
|
||||
|
||||
Для URL:
|
||||
|
||||
```
|
||||
https://example.com/items/foo
|
||||
```
|
||||
|
||||
...путь выглядит так:
|
||||
|
||||
```
|
||||
/items/foo
|
||||
```
|
||||
|
||||
!!! info "Дополнительная иформация"
|
||||
Термин "path" также часто называется "endpoint" или "route".
|
||||
|
||||
При создании API, "путь" является основным способом разделения "задач" и "ресурсов".
|
||||
|
||||
#### Операция (operation)
|
||||
|
||||
"Операция" это один из "методов" HTTP.
|
||||
|
||||
Таких, как:
|
||||
|
||||
* `POST`
|
||||
* `GET`
|
||||
* `PUT`
|
||||
* `DELETE`
|
||||
|
||||
...и более экзотических:
|
||||
|
||||
* `OPTIONS`
|
||||
* `HEAD`
|
||||
* `PATCH`
|
||||
* `TRACE`
|
||||
|
||||
По протоколу HTTP можно обращаться к каждому пути, используя один (или несколько) из этих "методов".
|
||||
|
||||
---
|
||||
|
||||
При создании API принято использовать конкретные HTTP-методы для выполнения определенных действий.
|
||||
|
||||
Обычно используют:
|
||||
|
||||
* `POST`: создать данные.
|
||||
* `GET`: прочитать.
|
||||
* `PUT`: изменить (обновить).
|
||||
* `DELETE`: удалить.
|
||||
|
||||
В OpenAPI каждый HTTP метод называется "**операция**".
|
||||
|
||||
Мы также будем придерживаться этого термина.
|
||||
|
||||
#### Определите *декоратор операции пути (path operation decorator)*
|
||||
|
||||
```Python hl_lines="6"
|
||||
{!../../../docs_src/first_steps/tutorial001.py!}
|
||||
```
|
||||
|
||||
Декоратор `@app.get("/")` указывает **FastAPI**, что функция, прямо под ним, отвечает за обработку запросов, поступающих по адресу:
|
||||
|
||||
* путь `/`
|
||||
* использующих <abbr title="HTTP GET метод"><code>get</code> операцию</abbr>
|
||||
|
||||
!!! info "`@decorator` Дополнительная информация"
|
||||
Синтаксис `@something` в Python называется "декоратор".
|
||||
|
||||
Вы помещаете его над функцией. Как красивую декоративную шляпу (думаю, что оттуда и происходит этот термин).
|
||||
|
||||
"Декоратор" принимает функцию ниже и выполняет с ней какое-то действие.
|
||||
|
||||
В нашем случае, этот декоратор сообщает **FastAPI**, что функция ниже соответствует **пути** `/` и **операции** `get`.
|
||||
|
||||
Это и есть "**декоратор операции пути**".
|
||||
|
||||
Можно также использовать операции:
|
||||
|
||||
* `@app.post()`
|
||||
* `@app.put()`
|
||||
* `@app.delete()`
|
||||
|
||||
И более экзотические:
|
||||
|
||||
* `@app.options()`
|
||||
* `@app.head()`
|
||||
* `@app.patch()`
|
||||
* `@app.trace()`
|
||||
|
||||
!!! tip "Подсказка"
|
||||
Вы можете использовать каждую операцию (HTTP-метод) по своему усмотрению.
|
||||
|
||||
**FastAPI** не навязывает определенного значения для каждого метода.
|
||||
|
||||
Информация здесь представлена как рекомендация, а не требование.
|
||||
|
||||
Например, при использовании GraphQL обычно все действия выполняются только с помощью POST операций.
|
||||
|
||||
### Шаг 4: определите **функцию операции пути**
|
||||
|
||||
Вот "**функция операции пути**":
|
||||
|
||||
* **путь**: `/`.
|
||||
* **операция**: `get`.
|
||||
* **функция**: функция ниже "декоратора" (ниже `@app.get("/")`).
|
||||
|
||||
```Python hl_lines="7"
|
||||
{!../../../docs_src/first_steps/tutorial001.py!}
|
||||
```
|
||||
|
||||
Это обычная Python функция.
|
||||
|
||||
**FastAPI** будет вызывать её каждый раз при получении `GET` запроса к URL "`/`".
|
||||
|
||||
В данном случае это асинхронная функция.
|
||||
|
||||
---
|
||||
|
||||
Вы также можете определить ее как обычную функцию вместо `async def`:
|
||||
|
||||
```Python hl_lines="7"
|
||||
{!../../../docs_src/first_steps/tutorial003.py!}
|
||||
```
|
||||
|
||||
!!! note "Технические детали"
|
||||
Если не знаете в чём разница, посмотрите [Конкурентность: *"Нет времени?"*](../async.md#in-a-hurry){.internal-link target=_blank}.
|
||||
|
||||
### Шаг 5: верните результат
|
||||
|
||||
```Python hl_lines="8"
|
||||
{!../../../docs_src/first_steps/tutorial001.py!}
|
||||
```
|
||||
|
||||
Вы можете вернуть `dict`, `list`, отдельные значения `str`, `int` и т.д.
|
||||
|
||||
Также можно вернуть модели Pydantic (рассмотрим это позже).
|
||||
|
||||
Многие объекты и модели будут автоматически преобразованы в JSON (включая ORM). Пробуйте использовать другие объекты, которые предпочтительней для Вас, вероятно, они уже поддерживаются.
|
||||
|
||||
## Резюме
|
||||
|
||||
* Импортируем `FastAPI`.
|
||||
* Создаём экземпляр `app`.
|
||||
* Пишем **декоратор операции пути** (такой как `@app.get("/")`).
|
||||
* Пишем **функцию операции пути** (`def root(): ...`).
|
||||
* Запускаем сервер в режиме разработки (`uvicorn main:app --reload`).
|
||||
|
|
@ -67,6 +67,7 @@ nav:
|
|||
- fastapi-people.md
|
||||
- python-types.md
|
||||
- Учебник - руководство пользователя:
|
||||
- tutorial/first-steps.md
|
||||
- tutorial/path-params.md
|
||||
- tutorial/query-params-str-validations.md
|
||||
- tutorial/path-params-numeric-validations.md
|
||||
|
|
|
|||
Loading…
Reference in New Issue