Встроенная документация с OpenAPI (Swagger)

Представьте, что вы создали полноценный API с множеством функций, но без документации. Для других разработчиков использование такого API будет похоже на работу с незнакомым инструментом без инструкции — придется методом проб и ошибок выяснять, какие команды доступны и как их правильно вызывать.

Именно поэтому документация API так важна. Она объясняет, как взаимодействовать с вашим сервисом: какие запросы можно отправлять, какие данные требуются и какие ответы ожидать.

OpenAPI — это стандарт документирования REST API, который FastAPI поддерживает "из коробки". Благодаря этому документация автоматически генерируется для каждого эндпоинта. Это дает вам:

• Наглядное представление всех доступных эндпоинтов API
• Четкое описание требуемых параметров и форматов данных
• Информацию о возможных ответах и кодах состояния
• Интерактивный интерфейс для тестирования запросов прямо в браузере

И что особенно ценно — всё это происходит автоматически, без необходимости писать дополнительный код!

---

Знакомство с OpenAPI и Swagger UI

FastAPI интегрируется с OpenAPI и предоставляет два удобных интерфейса для документирования и тестирования вашего API:

1. Swagger UI — это красивая панель в веб-интерфейсе, где вы можете видеть ваши эндпоинты, отправлять запросы и сразу проверять их ответы.
2. ReDoc — альтернативный интерфейс документации, с более строгим дизайном. Подходит для тех, кто любит минимализм.

Swagger UI доступен по умолчанию по адресу /docs, а ReDoc — на /redoc.

---

Практическое применение документации

Пора переходить от слов к делу. Давайте добавим несколько эндпоинтов в наше приложение и посмотрим, как автоматически генерируется документация.

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")
async def read_items(q: str = None):
    """
    Возвращает список предметов.
    Если указан параметр `q`, возвращает элементы, содержащие `q`.
    """
    if q:
        return {"items": [f"Item {i}" for i in range(1, 6) if q in f"Item {i}"]}
    return {"items": [f"Item {i}" for i in range(1, 6)]}

Шаг 1: Запустите приложение через Uvicorn:

uvicorn main:app --reload

Шаг 2: Откройте браузер и перейдите по адресу http://127.0.0.1:8000/docs.

Бум! Перед вами интерфейс Swagger UI. Здесь вы увидите эндпоинт /items/ и его описание. Вы можете щелкнуть на эндпоинт, указать параметры и отправить запрос прямо отсюда.

---

Настройка документации для эндпоинтов

FastAPI позволяет добавлять описание, заголовок и многое другое для каждого эндпоинта. Например, вы можете использовать description и summary, чтобы лучше описать ваш маршрут.

@app.get(
    "/users/",
    summary="Получить список пользователей",
    description="Этот эндпоинт возвращает список всех зарегистрированных пользователей. "
                "Можно использовать параметр `q` для фильтрации."
)
async def get_users(q: str = None):
    return {"users": ["Alice", "Bob", "Carol"]}

Теперь заголовок и описание маршрута отображаются в Swagger UI. Это делает документацию удобной для чтения и понимания.

---

Добавление примеров запросов и ответов

Если вы хотите показать, как работают ваши эндпоинты, вы можете добавить примеры запросов и ответов.

from fastapi.responses import JSONResponse

@app.get(
    "/products/",
    summary="Список продуктов",
    responses={
        200: {
            "description": "Успешное получение списка продуктов",
            "content": {
                "application/json": {
                    "example": {
                        "products": ["Product 1", "Product 2"]
                    }
                }
            }
        }
    }
)
async def get_products():
    return JSONResponse(content={"products": ["Product A", "Product B"]})

Теперь в Swagger UI вы увидите пример, который лучше объяснит другим разработчикам, чего ожидать от API.

---

Защита документации через конфигурацию

А что, если мы не хотим показывать документацию всем подряд? FastAPI позволяет ограничить доступ к документации. Например, вы можете отключить Swagger UI:

app = FastAPI(docs_url=None, redoc_url=None)

Теперь документация недоступна. Однако, вы можете создать скрытый эндпоинт для своих разработчиков:

from fastapi.openapi.utils import get_openapi

@app.get("/custom_docs")
async def custom_docs():
    return get_openapi(
        title="My API",
        version="1.0.0",
        description="Это мой кастомный API",
        routes=app.routes
    )

---

Как тестировать API через Swagger UI

Swagger UI не просто красивая документация. Это еще и мощный инструмент разработки! Вы можете:

1. Отправлять запросы с параметрами и получать данные.
2. Тестировать различные сценарии работы вашего API.
3. Изучать возможные HTTP-коды ответов.

Прямо в интерфейсе вы можете перейти к любому эндпоинту, нажать кнопку "Try it out" и протестировать запросы.

---

"Вау, а что ещё круто?"

FastAPI настолько умен, что автоматически конвертирует Pydantic-модели в схемы OpenAPI. Если вы определите Pydantic-модель для валидации данных, она сразу появится в документации.

Пример:

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = None

@app.post("/items/", response_model=Item)
async def create_item(item: Item):
    """
    Создает новый предмет.
    """
    return item

Swagger UI покажет детали модели Item и обязательные поля. Это поможет другим разработчикам понять, какие данные нужно отправлять.

---

Что делать, если возникли ошибки?

В процессе работы с документацией могут возникать ошибки. Например:

• Вы забыли описание параметра, и Swagger UI выглядит "пустовато".
• Вы указали неверные типы данных, и генерация схемы OpenAPI не работает.

В таком случае всегда полезно прочитать официальную документацию FastAPI. А ещё, помните — если в коде ошибка, Swagger UI об этом скажет!

---

Теперь в вашем арсенале есть не только умение создавать API, но и делать их понятными для других — с помощью OpenAPI и Swagger UI.

Поверьте, на собеседовании умение показать документацию API сразу добавит вам +100 очков! 🚀