Знакомство с FastAPI

Это неофициальный перевод документации FastAPI. Если у вас есть время и знания, можете помочь с официальным переводом здесь.

Введение

Весь использованный код можно копировать и использовать без изменений (этот код представляет собой проверенные python-файлы).

Для запуска любого из примеров нужно скопировать код в файл main.py и запустить uvicorn с помощью следующей команды:

uvicorn main:app --reload
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [28720]
INFO: Started server process [28722]
INFO: Waiting for application startup.
INFO: Application startup complete.

Крайне рекомендуется писать или копировать код и запускать локально. Использование его в редакторе показывает основные преимущества FastAPI. Можно видеть, насколько мало кода нужно писать: все проверки типов, автозаполнения и так далее.

Установка FastAPI

Первый шаг — установка FastAPI.

При первом знакомстве лучше установить его вместе со всеми опциональными зависимостями и возможностями:

pip install fastapi[all]

… что также включает uvicorn, который может быть использован как сервер для запуска кода.

Примечание

Можно также выполнить установку частями. Это может потребоваться при развертывании приложения:
pip install fastapi
Также нужно установить uvicorn, чтобы он работал как сервер:
pip install uvicorn
И так для каждой зависимости.

Первый запуск приложения

Простейший файл FastAPI может выглядеть вот так:


from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
return {"message": "Hello World"}

Скопируйте содержимое в файл main.py и запустите сервер:

$ uvicorn main:app --reload

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [60] using statreload
INFO:     Started server process [62]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

Примечание

Команда uvicorn main:app ссылается на:
* main: файл main.py (модуль Python).
* app: объект, созданный внутри main.py на строке app = FastAPI().
* --reload: перезагружает сервер при изменениях кода. Используется только для разработки.

В выводе есть такая строка:

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Она показывает URL работы сервера на локальной машине.

Проверка работы

Перейдите в браузере по ссылке http://127.0.0.1:8000. Там отобразится ответ в формате JSON:

Автоматическая документация API

Теперь стоит перейти на http://127.0.0.1:8000/docs.

На этой странице находится интерактивная документация по API (предоставляемая Swagger UI):

Автоматическая документация API

Альтернативная документация API

Также можно попробовать http://127.0.0.1:8000/redoc.

Это альтернативный вариант автоматической документации (от ReDoc):

Знакомство с FastAPI

OpenAPI

FastAPI генерирует «схему» из API с помощью стандарта OpenAPI.

Схема

Схема (schema) — это определение или описание чего-либо. Не код, отвечающий за реализацию, а просто абстрактное описание.

API-схема

В этом случае OpenAPI — это спецификация, которая предписывает, как именно определять схему API. Определение включает пути, возможные принимаемые параметры и так далее.

Схема данных

Понятие «схема» может также указывать на форму некоторых данных: например, JSON-содержимое. В этом случае тут будут указываться JSON-атрибуты, использованные типы данных и другое.

OpenAPI и JSON Schema

OpenAPI определяет схему API для созданного API. А она, в свою очередь, включает определения отправленных или полученных через API данных с помощью JSON — стандарта схем данных JSON.

Проверка openapi.json

Если интересно узнать, как работает чистая схема OpenAPI, то FastAPI автоматически генерирует JSON-схему с описаниями API.

Их можно увидеть прямо на сайте: http://127.0.0.1:8000/openapi.json. Там будет показан JSON в таком формате:


{
"openapi":"3.0.2",
"info":{
"title":"FastAPI",
"version":"0.1.0"
},
"paths":{
"/":{
"get":{
"summary":"Root",
"operationId":"root__get",
"responses":{
"200":{
"description":"Successful Response",
"content":{
"application/json":{
"schema":{
...

Для чего нужен OpenAPI

Схема OpenAPI — это то, что отвечает за работу двух включенных интерактивных систем документации.

И есть десятки альтернатив, все из которых основаны на OpenAPI. Их можно запросто добавлять в приложение, построенное с помощью FastAPI.

Его также можно использовать для автоматической генерации кода, чтобы у клиентов была возможность взаимодействовать через API. Например, для фронтенда, мобильных или IoT-приложений.

Из чего состоит наше приложение

Шаг №1: импорт FastAPI

FastAPI — это класс Python, который предоставляет всю функциональность для API.

Технические подробности

FastAPI — это класс, который наследуется прямо от Starlette.
Все возможности Starlette также можно использовать с FastAPI.

Шаг №2: создание «экземпляра» FastAPI

Здесь переменная app будет экземпляром класса FastAPI. Она будет основной точкой взаимодействия для создания API. Это та же переменная, которая указывается в команде uvicorn: uvicorn main:app --reload

Если создать такое приложение:


from fastapi import FastAPI

my_awesome_api = FastAPI()

@my_awesome_api.get("/")
async def root():
return {"message": "Hello World"}

И сохранить его в файле main.py, то вызов uvicorn будет приблизительно следующим:

uvicorn main:my_awesome_api --reload

Шаг №3: создание операции пути

Путь здесь указывает на последнюю часть URL, начиная с первой косой черты /.

Так, в URL https://example.com/items/foo значение пути будет — /items/foo.

Информация

«Путь» также часто называют конечной точкой (endpoint) или маршрутом (route).

При создании API «путь» — это основной способ разделения «concerns» и «resources».

Операция здесь — это один из HTTP-методов:

  • POST
  • GET
  • PUT
  • DELETE
  • OPTIONS
  • HEAD
  • PATCH
  • TRACE

В протоколе HTTP с каждым путем можно взаимодействовать с помощью одного из таких методов.

При создании API обычно эти методы выполняют определенное действие:

  • POST — создает данные
  • GET — читает данные
  • PUT — обновляет данные
  • DELETE — удаляет данные

В OpenAPI каждый из таких методов называется operations.

Объявление декоратора операции пути:

@app.get("/") сообщает FastAPI, что следующая функция отвечает за обработку запросов к:

  • пути /,
  • с помощью операции get.

О @декораторах

Синтаксис @something обозначает декораторы в Python. Они задаются в верхней части функции. Декоратор принимает функцию и что-то с ней делает.
В этом случае декоратор сообщает FastAPI, что функция ниже соответствует пути / и операции get. Это и есть декоратор операции пути.

Также можно использовать другие операции:

  • @app.post()
  • @app.put()
  • @app.delete()

И более редкие:

  • @app.options()
  • @app.head()
  • @app.patch()
  • @app.trace()

Рекомендация

Можно использовать любую операцию (любой HTTP-метод). FastAPI не требует какого-то специального значения. Представленная здесь информация — это рекомендация, а не требование.
Например, при использовании GraphQL обычно все действия выполняются с помощью операций POST.

Шаг №4: создание функции операции пути

Наша «функция операции пути»:

  • Путь — /;
  • Операция — get;
  • Функция — функция под декоратором @app.get("/").

Это функция Python. Она будет вызвана FastAPI в момент получения запроса к URL / с помощью операции GET. В данном случае это асинхронная функция. Ее можно определить и как обычную (без async def):


from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def root():
return {"message": "Hello World"}

Если вы не знаете разницы, читайте: Async: «In a hurry? (ENG)

Шаг №5: возвращение ответа

Можно вернуть dict, list или одиночные значения: str, int и так далее. Также можно возвращать модели Pydantic.

Есть масса других объектов и моделей, которые будут автоматически конвертированы в JSON (включая ORM и так далее).

Резюмируем

  • Импортируем FastAPI,
  • Создаем экземпляр app,
  • Пишем декоратор операции пути (например, @app.get("/")),
  • Пишем функцию операции пути (например, def root(): ...),
  • Запускаем сервер разработки (например, uvicorn main:app --reload).

Обучение с трудоустройством

Профессия Python-разработчик / Skillbox

Профессия Python-разработчик / Skillbox

7 500 3 750 ₽/мес.
Факультет Python-разработки / GeekBrains

Факультет Python-разработки / GeekBrains

4 990 ₽/мес.
Факультет Аналитики Big Data / GeekBrains

Факультет Аналитики Big Data / GeekBrains

7 490 ₽/мес.
Профессия Data Scientist / Skillbox

Профессия Data Scientist / Skillbox

8 167 4 083 ₽/мес.

Тест на знание python

Что вернет следующий код?
Верно ли данное утверждение: "В Python есть два типа чисел: целые числа и числа с плавающей точкой"?
Что выведет этот код?
Какой будет результат выполнения этого кода?
Что выведет этот код?
Александр
Я создал этот блог в 2018 году, чтобы распространять полезные учебные материалы, документации и уроки на русском. На сайте опубликовано множество статей по основам python и библиотекам, уроков для начинающих и примеров написания программ.