Глава 6.4: Документирование API

Время изучения: 30 минут

1. Зачем нужна документация API?

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

Хорошая документация:

Экономит время: Разработчикам не нужно гадать, какие эндпоинты существуют, какие параметры они принимают и что возвращают.
Уменьшает ошибки: Четкое описание форматов данных и кодов ошибок помогает избежать неправильного использования API.
Упрощает интеграцию: Frontend-команда может работать параллельно с backend-командой, опираясь на документацию как на контракт.
Является вашим наследием: Через полгода вы сами скажете себе спасибо, когда вернетесь к проекту.

💡 Космическая аналогия:

API = Сложная система управления космической станцией.

Документация API = Руководство для астронавтов. В нем описано:

Какую команду (эндпоинт) отправить, чтобы открыть шлюз.

Какие параметры (тело запроса) передать, чтобы настроить систему жизнеобеспечения.

Какие сигналы (ответы API) ожидать в ответ.

2. Документация в FastAPI: Автоматическая магия

FastAPI делает документирование невероятно простым. Он автоматически генерирует интерактивную документацию на основе вашего кода, используя стандарты OpenAPI и Swagger UI.

Шаг 1: Добавьте метаданные в ваше приложение

В main.py можно добавить описания, которые появятся в документации.

# main.py
from fastapi import FastAPI
from pydantic import BaseModel, Field

# ... (код FastAPI)

app = FastAPI(
    title="SpaceAPI",
    description="""
API для исследования галактики. 🚀

Вы сможете:
* **Просматривать планеты**.
* **Добавлять новые миры** (требуется аутентификация).
    """,
    version="1.0.0",
    contact={
        "name": "Главный инженер ЦУП",
        "url": "https://example.com/contact",
        "email": "engineer@example.com",
    },
)

Шаг 2: Опишите ваши модели и эндпоинты

Чем детальнее вы опишете Pydantic-модели и параметры эндпоинтов, тем лучше будет документация.

# В файле с Pydantic-моделями или в main.py

class PlanetBase(BaseModel):
    name: str = Field(..., example="Земля", description="Название планеты")
    description: str = Field(..., example="Голубая планета с разнообразной жизнью", description="Краткое описание")
    # ...

class Planet(PlanetBase):
    id: int
    is_habitable: bool

    class Config:
        orm_mode = True # или from_attributes = True в Pydantic v2

# В файле с роутами
@router.get(
    "/planets",
    response_model=list[Planet],
    summary="Получить список всех планет",
    description="Возвращает список всех известных планет с пагинацией (в будущем)."
)
def get_planets():
    # ...

@router.post(
    "/planets",
    # ...
    summary="Создать новую планету",
    responses={
        401: {"description": "Пользователь не авторизован"},
        422: {"description": "Ошибка валидации данных"}
    }
)
def create_planet(planet: PlanetCreate, ...):
    # ...

Field(..., example="..."): Добавляет примеры в документацию.
summary: Краткое описание эндпоинта.
description: Подробное описание.
responses: Описание возможных кодов ответа, кроме успешного.

Шаг 3: Откройте документацию в браузере

Запустите ваш FastAPI сервер и откройте два волшебных URL:

http://127.0.0.1:8000/docs — откроет интерактивную документацию Swagger UI. Здесь вы можете не только читать, но и тестировать ваши эндпоинты прямо из браузера!
http://127.0.0.1:8000/redoc — откроет альтернативный вид документации ReDoc. Он менее интерактивный, но часто более читабельный.

3. Документация в Laravel: Используем сторонние пакеты

В отличие от FastAPI, Laravel не генерирует документацию "из коробки". Однако существуют отличные пакеты, которые делают это, анализируя ваш код. Самый популярный — Scribe.

Шаг 1: Установка Scribe

composer require --dev "knuckleswtf/scribe"

php artisan vendor:publish --tag=scribe-config
php artisan scribe:generate

Шаг 2: Описание эндпоинтов с помощью DocBlocks

Scribe читает PHP DocBlocks (комментарии вида /** ... */) над методами вашего контроллера.

Откройте app/Http/Controllers/PlanetController.php:

// app/Http/Controllers/PlanetController.php

/**
 * @group Планеты
 * API для управления планетами
 */
class PlanetController extends Controller
{
    /**
     * Получить список планет
     *
     * Возвращает пагинированный список всех планет в галактике.
     *
     * @unauthenticated
     */
    public function index()
    {
        // ...
    }

    /**
     * Создать новую планету
     *
     * @authenticated
     *
     * @bodyParam name string required Название планеты. Example: Kepler-186f
     * @bodyParam description string required Описание планеты.
     * @bodyParam size_km integer required Диаметр в километрах. Example: 14000
     * @bodyParam is_habitable boolean Обитаема ли планета. Example: true
     *
     * @response 201 {
     *  "id": 4,
     *  "name": "Kepler-186f",
     *  "description": "Первая подтвержденная планета размером с Землю в обитаемой зоне другой звезды.",
     *  "size_km": 14000,
     *  "is_habitable": true,
     *  "created_at": "2023-10-27T12:00:00.000000Z",
     *  "updated_at": "2023-10-27T12:00:00.000000Z"
     * }
     */
    public function store(Request $request)
    {
        // ...
    }
    // ... и так далее для других методов
}

Ключевые теги Scribe:

@group: Группирует эндпоинты.
@unauthenticated / @authenticated: Указывает, нужен ли токен.
@bodyParam: Описывает параметр в теле запроса.
@response: Пример успешного ответа.

Шаг 3: Генерация и просмотр документации

Каждый раз после внесения изменений в DocBlocks, запускайте команду:

php artisan scribe:generate

Scribe создаст статическую HTML-страницу с вашей документацией. Откройте ее по адресу: http://your-app-url/docs.

Квиз для закрепления

🚀 Итог главы:

Вы создали профессиональную документацию, превратив ваши API из "черных ящиков" в понятные и удобные инструменты.

✅ Поняли критическую важность документирования API.
🪄 Научились использовать автоматическую генерацию документации в FastAPI.
⚙️ Освоили основы пакета Scribe для документирования API на Laravel.
🛰️ Убедились, что хорошая документация — лучший помощник для любого разработчика.

Ваши API теперь не только работают и защищены, но и полностью готовы к использованию другими членами команды. Остался последний, но самый важный шаг — финальная проверка безопасности.

📌 Проверка:

Для FastAPI: откройте /docs в браузере и попробуйте выполнить GET-запрос к списку планет прямо из интерфейса Swagger UI.

Для Laravel: выполните php artisan scribe:generate и откройте /docs. Убедитесь, что эндпоинты сгруппированы, а у метода store есть описание параметров.