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

FastAPI автоматически создаёт интерактивную документацию API на основе аннотаций типов в коде, по умолчанию предоставляя два интерфейса: Swagger UI и ReDoc. Разработчики могут тестировать API прямо в документации без каких-либо дополнительных инструментов.

Доступ к документации API

После запуска приложения FastAPI перейдите по следующему адресу для просмотра документации:

АдресТип документаОсобенности
http://127.0.0.1:8000/docsSwagger UIИнтерактивное тестирование: нажмите "Try it out", чтобы отправить запросы.
http://127.0.0.1:8000/redocReDocУдобное чтение, подходит для просмотра и обращения к определениям API.
http://127.0.0.1:8000/openapi.jsonOpenAPI JSONНеобработанная спецификация OpenAPI в формате JSON, доступная для использования инструментами.

Swagger UI

Swagger UI предоставляет интуитивно понятный пользовательский интерфейс для тестирования API прямо в браузере:

Шаги для тестирования API

  1. Нажмите на маршрут, который хотите протестировать, чтобы развернуть его подробности
  2. Нажмите кнопку"Try it out"Button
  3. Заполните значения параметров
  4. Нажмите кнопку"Execute", чтобы отправить запрос
  5. Просмотрите результаты ответа

ReDoc

ReDoc ориентирован на читаемость документации, подходит для просмотра определений API:

Спецификация OpenAPI

Использование FastAPIOpenAPIСтандарт преобразует API в «схемы». Посетитеhttp://127.0.0.1:8000/openapi.jsonВы можете просмотреть необработанный JSON OpenAPI:

{
    "openapi": "3.1.0",
    "info": {
        "title": "FastAPI",
        "version": "0.1.0"
    },
    "paths": {
        "/items/{item_id}": {
            "get": {
                "responses": {
                    "200": {
                        "description": "Successful Response"
                    }
                }
            }
        }
    }
}

Назначение спецификации OpenAPI:

  • Обеспечивает работу систем документации Swagger UI и ReDoc
  • Автоматически генерировать клиентский код на различных языках
  • Интеграция с инструментами тестирования API (такими как Postman)
  • Совместимость с большим количеством сторонних инструментов и платформ

Настройка информации документации API

При создании экземпляра FastAPI можно настроить метаданные документации:

Пример

from fastapi import FastAPI

app = FastAPI(
    title="Мой API",                    # Название API
    description="Это пример API, демонстрирующий возможности настройки документации",  # Описание API
    version="1.0.0",                    # Версия API
    terms_of_service="http://example.com/terms/",  # URL условий обслуживания
    contact={                           # Контактная информация
        "name": "Разработчик",
        "url": "http://example.com/contact/",
        "email": "[email protected]",
    },
    license_info={                      # Информация о лицензии
        "name": "MIT",
        "url": "https://opensource.org/licenses/MIT",
    },
)

Добавьте информацию документации для маршрутов

Вы можете добавить подробную документационную информацию для каждого маршрута в декораторах и функциях:

Пример

from typing import Annotated
from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get(
    "/items/{item_id}",
    summary="Получение информации о товаре",              # Краткое описание
    description="Получить подробную информацию о товаре по ID товара",  # Подробное описание
    response_description=Объект информации о товаре,   # Описание ответа
    tags=["Управление товарами"],                   # Групповые теги
)
async def read_item(
    item_id: Annotated[int, Path(ge=1, description="ID товара")],
    q: Annotated[str | None, Query(description=“Ключевые слова для поиска”)] = Отсутствует,
):
    """
Получить информацию о товаре:

- **item_id**: Уникальный идентификатор товара.
- **q**: необязательное ключевое слово для поиска
    """
    return {"item_id": item_id, "q": q}

Описание параметра документации:

ПараметрPositionОписание
summaryдекораторКраткое описание маршрута, отображаемое в списке маршрутов.
descriptionдекораторПодробное описание маршрута, поддерживает Markdown.
response_descriptionдекораторОписание ответа
tagsдекораторГруппировка маршрутов, отображаемая по категориям тегов в документации.
строка документациитело функцииСтроки документации функции отображаются как описания.

Если оба заданы одновременноdescriptionи строка документации функции,descriptionИмеет приоритет. Строки документации поддерживают формат Markdown, подходящий для написания более длинных пояснений.

Группировка с помощью тегов

tagsПараметры могут объединять связанные маршруты для более наглядного отображения в документации:

Пример

from fastapi import FastAPI

app = FastAPI()


@app.get("/users/", tags=["User Management"])
async def read_users():
    return [{"username": "Rick"}, {"username": "Morty"}]


@app.get("/items/", tags=["Product Management"])
async def read_items():
    return [{"name": "Foo"}, {"name": "Bar"}]

В Swagger UI маршруты отображаются сгруппированными по тегам.

Отключение документации

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

Пример

from fastapi import FastAPI

# Отключение документации
app = FastAPI(docs_url=None, redoc_url=None)

Итог

  • FastAPI автоматически создает два типа интерактивной документации: Swagger UI и ReDoc
  • Содержимое документации автоматически генерируется на основе аннотаций типов в коде, и документация автоматически синхронизируется при обновлении кода
  • Использованиеtitle、description、tagsНастройте информацию документации с помощью таких параметров, как:
  • Строки документации функций также отображаются в документации.
  • Доступ к производственной среде можно получить черезdocs_url=NoneОтключение документации
Другие расширения