Перейти к содержанию

От переводчика

Это машинный перевод (DeepSeek) статьи https://fastapi.tiangolo.com/tutorial/first-steps

Версия от 03.09.2026

По этой теме хочу также рекомендовать свой разбор неочевидных моментов и сжатый пересказ в канале Макс.

Подпишитесь на канал "Изучаем FastAPI", чтобы ссылки на разбор сложных моментов работали.

Подпишитесь на канал "Первод курса FastAPI", чтобы ссылки работали.

 

Перевод прочих разделов документации буду по мере сил делать.

Обо мне

Первые шаги

Самый простой файл 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">&apos;/home/user/code/awesomeapp&apos;</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):

Swagger UI

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

А теперь перейдите по адресу http://127.0.0.1:8000/redoc.

Вы увидите альтернативную автоматическую документацию (предоставляемую 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 "методов".

Один из:

  • POST
  • GET
  • PUT
  • DELETE

...и более экзотические:

  • OPTIONS
  • HEAD
  • PATCH
  • TRACE

В протоколе 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.