Урок 11

Документация API

Хорошая документация — обязательная часть API. Без неё клиенты не знают, как использовать твои эндпоинты.

OpenAPI (Swagger)

OpenAPI — стандарт описания REST API. Документ в формате YAML или JSON описывает эндпоинты, параметры, ответы. На его основе генерируются интерактивные доки.

Инструменты

  • Swagger UI — интерактивная документация
  • L5-Swagger — пакет для Laravel
  • Scramble — автоматическая генерация из кода
  • Scribe — генерация из аннотаций

Scramble

Устанавливается одной командой:

composer require dedoc/scramble

После установки доступна страница /docs/api с интерактивной документацией. Scramble анализирует код контроллеров, ресурсы, Form Request и генерирует описание автоматически.

Аннотации

Некоторые пакеты используют аннотации в PHPDoc:

/**
 * @OA\Get(
 *     path="/api/posts",
 *     summary="Список постов",
 *     @OA\Response(response=200, description="OK")
 * )
 */
public function index() {}

Ручной формат

Если не хочешь ставить пакет — опиши API в markdown или на странице /docs. Главное, чтобы клиент понимал:

  • URL эндпоинта
  • HTTP-метод
  • Параметры (query, body, headers)
  • Формат запроса
  • Формат ответа
  • Возможные ошибки
  • Требуется ли аутентификация

Пример описания

GET /api/v1/posts

Query:
- page (integer, optional) — номер страницы
- per_page (integer, optional, max 100) — размер страницы
- search (string, optional) — поиск по заголовку

Headers:
- Accept: application/json

Response 200:
{
  "data": [
    {"id": 1, "title": "...", "slug": "..."}
  ],
  "meta": {...}
}

Тестирование через curl

Покажи примеры запросов:

curl -X GET http://api.example.com/api/v1/posts \
  -H "Accept: application/json"

curl -X POST http://api.example.com/api/v1/posts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"title": "New", "body": "Text"}'

Версии документации

Держи документацию в актуальном состоянии. Если эндпоинт изменился — обнови описание. Если удалил эндпоинт — удали из доков.