add first-steps chapter

tiangolo · Jul 20, 2021 · 54e1718 · 54e1718
1 parent d956f76
commit 54e1718
Show file tree

Hide file tree

Showing 3 changed files with 335 additions and 1 deletion.
diff --git a/docs/ru/docs/tutorial/first-steps.md b/docs/ru/docs/tutorial/first-steps.md
@@ -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"}
+```
+
+## Интерактивная документация
+
+Теперь перейдите на <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>):
+
+![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png)
+
+## Альтернативная документация
+
+А теперь перейдите на <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>.
+
+Вы увидите ещё одну автоматически сгенерированную интерактивную документацию API (предоставленную <a href="https://github.com/Rebilly/ReDoc" class="external-link" target="_blank">ReDoc</a>):
+
+![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png)
+
+## OpenAPI
+
+**FastAPI** генерирует "схему" по всему вашему API с помощью **OpenAPI** стандарта.
+
+### Схема
+
+Схема - это определение или описание чего-либо. Не код, который что-то реализует, а просто абстрактное описание.
+
+### Схема API
+
+В данном случае, <a href="https://github.com/OAI/OpenAPI-Specification" class="external-link" target="_blank">OpenAPI</a> - это спецификация, которая диктует, как определить схему вашего API.
+
+Это определение схемы включает пути вашего API, возможные параметры, которые они принимают, и т.д.
+
+### Схема данных
+
+Термин "схема" может относится и к данным, например, информации в формате JSON.
+
+В этом случае, она описывает атрибуты JSON и их типы, и т.п.
+
+### OpenAPI и JSON Schema
+
+OpenAPI определяет схему API вашего приложения. И эта схема включает определения (или "схемы") данных, отправляемых и получаемых вашим API с помощью **JSON Schema**, стандарта для схем данных JSON.
+
+### Проверяем `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**.
+
+Также вы можете её использовать для автоматической генерации кода для клиентских приложений, которые взаимодействуют с вашим API. Например, интерфейсные, мобильные или IoT-приложения.
+
+## Резюме, шаг за шагом
+
+### Шаг 1: импортируем `FastAPI`
+
+```Python hl_lines="1"
+{!../../../docs_src/first_steps/tutorial001.py!}
+```
+
+`FastAPI` - это класс Python, обеспечивающий всю функциональность для вашего API.
+
+!!! note "Технические детали"
+    Класс `FastAPI` наследует напрямую от `Starlette`.
+
+    Поэтому, чере `FastAPI` вам также доступны и все возможности <a href="https://www.starlette.io/" class="external-link" target="_blank">Starlette</a>.
+
+### Шаг 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: создаем *действие-путь*
+
+#### Путь
+
+"Путь" в данном случае означает часть URL начинающуюся с первого `/` (прим.пер.: после имени хоста).
+
+Т.е., для URL:
+
+```
+https://example.com/items/foo
+```
+
+...путем будет:
+
+```
+/items/foo
+```
+
+!!! info "Примечание"
+    "Путь" также еще называют "эндпоинтом" (endpoint) или "маршрутом" (route).
+
+В процессе построения API, "путь" - это основной способ разделить "проблемы" и "ресурсы".
+
+#### Действие
+
+Под "действием" понимается один из "методов" HTTP.
+
+Один из:
+
+* `POST`
+* `GET`
+* `PUT`
+* `DELETE`
+
+...или более экзотических:
+
+* `OPTIONS`
+* `HEAD`
+* `PATCH`
+* `TRACE`
+
+В HTTP-протоколе вы можете взаимодействовать с каждым "путем", используя один (или более) из этих "методов".
+
+---
+
+Для API мы обычно используем эти HTTP-методы для выполнения определенных действий.
+
+Обычно, мы используем:
+
+* `POST`: для создания данных.
+* `GET`: для чтения данных.
+* `PUT`: для обновления данных.
+* `DELETE`: для удаления данных.
+
+Поэтому в OpenAPI каждый из этих HTTP-методов называется "действие".
+
+Мы тоже будем называть их "**действия**".
+
+#### Задаем *путь-действие-декоратор*
+
+```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**, когда он получит запрос на URL `/` с методом `GET`.
+
+В данном случае это асинхронная (`async`) функция.
+
+---
+
+Вы также можете определить ее как обычную функцию вместо `async def`:
+
+```Python hl_lines="7"
+{!../../../docs_src/first_steps/tutorial003.py!}
+```
+
+!!! note "Примечание"
+    Если вы не знаете, в чем разница, ознакомьтесь с разделом [Async: *"Торопитесь?"*](../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`).
diff --git a/docs/ru/docs/tutorial/index.md b/docs/ru/docs/tutorial/index.md
@@ -52,7 +52,7 @@ $ pip install fastapi[all]
 
 ...которые включают `uvicorn`, используемый в качестве сервера, который запускает ваш код.
 
-!!! Примечание
+!!! note Примечание
     Также вы можете установить фреймворк и по частям.
 
     Для того, чтобы запустить ваше приложение в продуктовой среде, вам необходимо выполнить команды (скорее всего, единожды):

diff --git a/docs/ru/mkdocs.yml b/docs/ru/mkdocs.yml
@@ -54,6 +54,7 @@ nav:
   - zh: /zh/
 - Руководство пользователя:
   - tutorial/index.md
+  - tutorial/first-steps.md
 markdown_extensions:
 - toc:
     permalink: true