Первые шаги¶
Самый простой файл FastAPI может выглядеть так:
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
Скопируйте это в файл main.py.
Совет
FastAPI имеет официальное расширение для VS Code (и Cursor), которое предоставляет множество функций, включая обозреватель операций пути, поиск операций пути, навигацию CodeLens в тестах (переход к определению из тестов), а также развертывание в FastAPI Cloud и просмотр логов прямо из вашего редактора.
Запустите живой сервер:
$ <font color="#4E9A06">uv run fastapi</font> dev
<span style="background-color:#009485"><font color="#D3D7CF"> FastAPI </font></span> Запуск сервера разработки 🚀
Поиск структуры пакетов в директориях
с файлами <font color="#3465A4">__init__.py</font>
Импорт из <font color="#75507B">/home/user/code/</font><font color="#AD7FA8">awesomeapp</font>
<span style="background-color:#007166"><font color="#D3D7CF"> модуль </font></span> 🐍 main.py
<span style="background-color:#007166"><font color="#D3D7CF"> код </font></span> Импорт объекта FastAPI приложения из модуля с
следующим кодом:
<u style="text-decoration-style:solid">from </u><u style="text-decoration-style:solid"><b>main</b></u><u style="text-decoration-style:solid"> import </u><u style="text-decoration-style:solid"><b>app</b></u>
<span style="background-color:#007166"><font color="#D3D7CF"> app </font></span> Использование строки импорта: <font color="#3465A4">main:app</font>
<span style="background-color:#007166"><font color="#D3D7CF"> сервер </font></span> Сервер запущен на <font color="#729FCF"><u style="text-decoration-style:solid">http://127.0.0.1:8000</u></font>
<span style="background-color:#007166"><font color="#D3D7CF"> сервер </font></span> Документация по адресу <font color="#729FCF"><u style="text-decoration-style:solid">http://127.0.0.1:8000/docs</u></font>
<span style="background-color:#007166"><font color="#D3D7CF"> совет </font></span> Запуск в режиме разработки, для продакшена используйте:
<b>fastapi run</b>
Логи:
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Будет отслеживать изменения в этих директориях:
<b>[</b><font color="#4E9A06">'/home/user/code/awesomeapp'</font><b>]</b>
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Uvicorn запущен на <font color="#729FCF"><u style="text-decoration-style:solid">http://127.0.0.1:8000</u></font> <b>(</b>Нажмите CTRL+C
для выхода<b>)</b>
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Запущен процесс перезагрузки <b>[</b><font color="#34E2E2"><b>383138</b></font><b>]</b> с использованием WatchFiles
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Запущен серверный процесс <b>[</b><font color="#34E2E2"><b>383153</b></font><b>]</b>
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Ожидание запуска приложения.
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Запуск приложения завершен.
В выводе есть строка, содержащая что-то вроде:
INFO: Uvicorn запущен на http://127.0.0.1:8000 (Нажмите CTRL+C для выхода)
Эта строка показывает 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 для определения API.
"Схема"¶
"Схема" — это определение или описание чего-либо. Не код, который это реализует, а просто абстрактное описание.
"Схема" API¶
В данном случае OpenAPI — это спецификация, которая предписывает, как определять схему вашего API.
Это определение схемы включает пути вашего API, возможные параметры, которые они принимают, и т. д.
"Схема" данных¶
Термин "схема" также может относиться к форме некоторых данных, например, содержимому JSON.
В этом случае это означало бы атрибуты JSON и типы данных, которые они имеют, и т. д.
OpenAPI и JSON Schema¶
OpenAPI определяет схему API для вашего API. И эта схема включает определения (или "схемы") данных, отправляемых и получаемых вашим API, с использованием JSON Schema — стандарта для схем данных JSON.
Проверьте openapi_2dTL.json¶
Если вам интересно, как выглядит необработанная схема OpenAPI, FastAPI автоматически генерирует JSON (схему) с описаниями всего вашего API.
Вы можете увидеть его напрямую по адресу: http://127.0.0.1:8000/openapi_2dTL.json.
Он покажет JSON, начинающийся с чего-то вроде:
{
"openapi": "3.1.0",
"info": {
"title": "FastAPI",
"version": "0.1.0"
},
"paths": {
"/items/": {
"get": {
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
...
Для чего нужен OpenAPI¶
Схема OpenAPI — это то, что обеспечивает работу двух включенных интерактивных систем документации.
И существуют десятки альтернатив, все основанные на OpenAPI. Вы можете легко добавить любую из этих альтернатив в свое приложение, созданное с помощью FastAPI.
Вы также можете использовать его для автоматической генерации кода для клиентов, которые взаимодействуют с вашим API. Например, для фронтенд-, мобильных или IoT-приложений.
Настройте entrypoint приложения в pyproject.toml¶
Вы можете настроить, где находится ваше приложение, в файле pyproject.toml, например:
[tool.fastapi]
entrypoint = "main:app"
Эта запись entrypoint укажет команде fastapi, что она должна импортировать приложение следующим образом:
from main import app
Если ваш код был структурирован так:
.
├── backend
│ ├── main.py
│ ├── __init__.py
Тогда вы бы установили entrypoint как:
[tool.fastapi]
entrypoint = "backend.main:app"
что было бы эквивалентно:
from backend.main import app
fastapi dev с путём или с опцией CLI --entrypoint¶
Вы также можете передать путь к файлу в команду fastapi dev, и она определит объект приложения FastAPI для использования:
$ uv run fastapi dev main.py
Или вы также можете передать опцию --entrypoint в команду fastapi dev:
$ uv run fastapi dev --entrypoint main:app
Но вам пришлось бы запоминать правильный путь/точку входа каждый раз при вызове команды fastapi.
Кроме того, другие инструменты могут не найти его, например расширение VS Code или FastAPI Cloud, поэтому рекомендуется использовать entrypoint в pyproject.toml.
Разверните ваше приложение (опционально)¶
Вы можете развернуть ваше FastAPI приложение в FastAPI Cloud одной командой. 🚀
$ uv run fastapi deploy
Развертывание в FastAPI Cloud...
✅ Развертывание успешно!
🐔 Приготовьте курицу! Ваше приложение готово по адресу https://myapp.fastapicloud.dev
Интерфейс командной строки автоматически обнаружит ваше FastAPI приложение и развернет его в облаке. Если вы не вошли в систему, ваш браузер откроется для завершения процесса аутентификации.
Вот и все! Теперь вы можете получить доступ к своему приложению по этому URL-адресу. ✨
Краткое повторение, шаг за шагом¶
Шаг 1: импортируйте FastAPI¶
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
FastAPI — это класс Python, который предоставляет всю функциональность для вашего API.
Технические детали
FastAPI — это класс, который наследуется напрямую от Starlette.
Вы можете использовать всю функциональность Starlette с FastAPI.
Шаг 2: создайте "экземпляр" FastAPI¶
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
Здесь переменная app будет "экземпляром" класса FastAPI.
Это будет основная точка взаимодействия для создания всего вашего API.
Шаг 3: создайте операцию пути¶
Путь¶
"Путь" здесь относится к последней части URL-адреса, начиная с первого /.
Итак, в URL-адресе типа:
https://example.com/items/foo
...путь будет:
/items/foo
Примечание
"Путь" также часто называют "конечной точкой" (endpoint) или "маршрутом" (route).
При создании API "путь" является основным способом разделения "областей ответственности" и "ресурсов".
Операция¶
"Операция" здесь относится к одному из HTTP "методов".
Один из:
POSTGETPUTDELETE
...и более экзотические:
OPTIONSHEADPATCHTRACE
В протоколе HTTP вы можете обмениваться данными с каждым путем, используя один (или несколько) из этих "методов".
При создании API вы обычно используете эти конкретные HTTP-методы для выполнения определенного действия.
Обычно вы используете:
POST: для создания данных.GET: для чтения данных.PUT: для обновления данных.DELETE: для удаления данных.
Итак, в OpenAPI каждый из HTTP-методов называется "операцией".
Мы тоже будем называть их "операциями".
Определите декоратор операции пути¶
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
Конструкция @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("/")).
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
Это функция Python.
Она будет вызвана FastAPI при получении запроса по URL-адресу "/" с использованием операции GET.
В данном случае это async функция.
Вы также можете определить ее как обычную функцию вместо async def:
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def root():
return {"message": "Hello World"}
Примечание
Если вы не знаете разницу, ознакомьтесь с разделом Async: "Торопитесь?".
Шаг 5: верните содержимое¶
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
Вы можете вернуть dict, list, отдельные значения, такие как str, int и т. д.
Вы также можете вернуть модели Pydantic (вы узнаете об этом позже).
Существует множество других объектов и моделей, которые будут автоматически преобразованы в JSON (включая ORM и т. д.). Попробуйте использовать свои любимые — вполне вероятно, что они уже поддерживаются.
Шаг 6: Разверните его¶
Разверните ваше приложение в FastAPI Cloud одной командой: fastapi deploy. 🎉
О FastAPI Cloud¶
FastAPI Cloud создан тем же автором и командой, что и FastAPI.
Он упрощает процесс создания, развертывания и доступа к API с минимальными усилиями.
Он обеспечивает тот же опыт разработчика, что и создание приложений с FastAPI, для развертывания их в облаке. 🎉
FastAPI Cloud является основным спонсором и источником финансирования проектов с открытым исходным кодом FastAPI и друзья. ✨
Развертывание на других облачных провайдерах¶
FastAPI является открытым и основан на стандартах. Вы можете развертывать приложения FastAPI на любом облачном провайдере по вашему выбору.
Следуйте руководствам вашего облачного провайдера по развертыванию приложений FastAPI у них. 🤓
Резюме¶
- Импортируйте
FastAPI. - Создайте экземпляр
app. - Напишите декоратор операции пути, используя декораторы, такие как
@app.get("/"). - Определите функцию операции пути; например,
def root(): .... - Запустите сервер разработки с помощью команды
fastapi dev. - При желании разверните ваше приложение с помощью
fastapi deploy.