Browse Source
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Vladislav Kramorenko <[email protected]> Co-authored-by: Sebastián Ramírez <[email protected]>pull/9517/merge
Artem Golicyn
2 years ago
committed by
GitHub
GitHub
2 changed files with 334 additions and 0 deletions
@ -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`). |
|||
Loading…
Reference in new issue