Первые шаги¶

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

from fastapi import FastAPI

app = FastAPI()


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

Скопируйте в файл main.py.

Запустите сервер в режиме реального времени:

$ 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.

Технические детали

Команда 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):

Swagger UI

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

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

Вы увидите альтернативную автоматически сгенерированную документацию (предоставленную ReDoc):

ReDoc

OpenAPI¶

FastAPI генерирует "схему" всего API, используя стандарт OpenAPI.

"Схема"¶

"Схема" - это определение или описание чего-либо. Не код, реализующий это, а только абстрактное описание.

API "схема"¶

OpenAPI - это спецификация, которая определяет, как описывать схему API.

Определение схемы содержит пути (paths) API, их параметры и т.п.

"Схема" данных¶

Термин "схема" также может относиться к формату или структуре некоторых данных, например, JSON.

Тогда, подразумеваются атрибуты JSON, их типы данных и т.п.

OpenAPI и JSON Schema¶

OpenAPI описывает схему API. Эта схема содержит определения (или "схемы") данных, отправляемых и получаемых API. Для описания структуры данных в JSON используется стандарт JSON Schema.

Рассмотрим `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": {
        "/items/": {
            "get": {
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {



...

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

Схема OpenAPI является основой для обеих систем интерактивной документации.

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

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

Рассмотрим поэтапно¶

Шаг 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.

Именно к этой переменной app обращается uvicorn в команде:

$ uvicorn main:app --reload

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

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

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

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Шаг 3: определите операцию пути (path operation)¶

Путь (path)¶

"Путь" это часть URL, после первого символа /, следующего за именем домена.

Для URL:

https://example.com/items/foo

...путь выглядит так:

/items/foo

Дополнительная иформация

Термин "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)¶

from fastapi import FastAPI

app = FastAPI()


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

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

путь /
использующих get операцию

@decorator Дополнительная информация

Синтаксис @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 будет вызывать её каждый раз при получении GET запроса к URL "/".

В данном случае это асинхронная функция.

Вы также можете определить ее как обычную функцию вместо async def:

from fastapi import FastAPI

app = FastAPI()


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

Технические детали

Если не знаете в чём разница, посмотрите Конкурентность: "Нет времени?".

Шаг 5: верните результат¶

from fastapi import FastAPI

app = FastAPI()


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

Вы можете вернуть dict, list, отдельные значения str, int и т.д.

Также можно вернуть модели Pydantic (рассмотрим это позже).

Многие объекты и модели будут автоматически преобразованы в JSON (включая ORM). Пробуйте использовать другие объекты, которые предпочтительней для Вас, вероятно, они уже поддерживаются.

Резюме¶

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

Первые шаги¶

Проверьте¶

Интерактивная документация API¶

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

OpenAPI¶

"Схема"¶

API "схема"¶

"Схема" данных¶

OpenAPI и JSON Schema¶

Рассмотрим openapi.json¶

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

Рассмотрим поэтапно¶

Шаг 1: импортируйте FastAPI¶

Шаг 2: создайте экземпляр FastAPI¶

Шаг 3: определите операцию пути (path operation)¶

Путь (path)¶

Операция (operation)¶

Определите декоратор операции пути (path operation decorator)¶

Шаг 4: определите функцию операции пути¶

Шаг 5: верните результат¶

Резюме¶

Рассмотрим `openapi.json`¶

Шаг 1: импортируйте `FastAPI`¶

Шаг 2: создайте экземпляр `FastAPI`¶