Это неофициальный перевод документации FastAPI. Если у вас есть время и знания, можете помочь с официальным переводом здесь.
Введение
Весь использованный код можно копировать и использовать без изменений (этот код представляет собой проверенные python-файлы).
Для запуска любого из примеров нужно скопировать код в файл main.py и запустить uvicorn с помощью следующей команды:
uvicorn main:app --reloadINFO: 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:
{"message": "Hello World"}
Автоматическая документация API
Теперь стоит перейти на http://127.0.0.1:8000/docs.
На этой странице находится интерактивная документация по API (предоставляемая Swagger UI):
Альтернативная документация API
Также можно попробовать http://127.0.0.1:8000/redoc.
Это альтернативный вариант автоматической документации (от ReDoc):
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.
from fastapi import FastAPI
...
Технические подробности
FastAPI— это класс, который наследуется прямо от Starlette.
Все возможности Starlette также можно использовать с FastAPI.
Шаг №2: создание «экземпляра» FastAPI
...
app = 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-методов:
POSTGETPUTDELETEOPTIONSHEADPATCHTRACE
В протоколе HTTP с каждым путем можно взаимодействовать с помощью одного из таких методов.
При создании API обычно эти методы выполняют определенное действие:
POST— создает данныеGET— читает данныеPUT— обновляет данныеDELETE— удаляет данные
В OpenAPI каждый из таких методов называется operations.
Объявление декоратора операции пути:
...
@app.get("/")
...
@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("/").
...
async def root():
...
Это функция 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: возвращение ответа
...
return {"message": "Hello World"}
Можно вернуть dict, list или одиночные значения: str, int и так далее. Также можно возвращать модели Pydantic.
Есть масса других объектов и моделей, которые будут автоматически конвертированы в JSON (включая ORM и так далее).
Резюмируем
- Импортируем
FastAPI, - Создаем экземпляр
app, - Пишем декоратор операции пути (например,
@app.get("/")), - Пишем функцию операции пути (например,
def root(): ...), - Запускаем сервер разработки (например,
uvicorn main:app --reload).
