Swagger-PHP для PHP: полное руководство с примерами

Что такое Swagger-PHP и зачем он нужен?

Swagger-PHP — это мощная PHP-библиотека для автоматической генерации документации REST API в формате OpenAPI (ранее известном как Swagger). Вместо того чтобы вручную писать документацию в YAML или JSON, вы описываете API прямо в коде с помощью аннотаций PHPDoc. Библиотека анализирует эти аннотации и генерирует полную спецификацию OpenAPI, которую можно визуализировать с помощью Swagger UI, ReDoc или других инструментов.

Зачем это нужно?

• Автоматизация: Документация всегда синхронизирована с кодом. Изменили эндпоинт — обновили аннотацию, и документация готова.
• Стандартизация: OpenAPI — это индустриальный стандарт описания REST API, поддерживаемый сотнями инструментов.
• Удобство для фронтенда: Разработчики клиентских приложений могут импортировать спецификацию в Postman, Insomnia или сгенерировать клиентский код.
• Тестирование: Спецификацию можно использовать для автоматического тестирования API.
• Интерактивная документация: Swagger UI позволяет тестировать эндпоинты прямо из браузера.

Установка Swagger-PHP

Установка производится через Composer — стандартный менеджер пакетов для PHP. Откройте терминал в корневой директории вашего проекта и выполните:

composer require zircote/swagger-php

Если вы используете Laravel, Symfony или другой фреймворк, установка не отличается. После установки в вашем проекте появится папка vendor/zircote/swagger-php.

Дополнительно (опционально): Для визуализации документации вам понадобится Swagger UI. Вы можете установить его через npm:

npm install swagger-ui-dist

Или просто скачать готовую сборку с официального сайта Swagger.

Быстрый старт с примером кода

Давайте создадим простой API для управления списком задач (Todo List) и сгенерируем для него документацию.

Шаг 1: Создайте файл index.php с вашим API:

<?php
/**
 * @OA\Info(
 *     title="Todo API",
 *     version="1.0.0",
 *     description="Простой API для управления задачами"
 * )
 * @OA\Server(
 *     url="http://localhost:8000",
 *     description="Локальный сервер"
 * )
 */

use OpenApi\Annotations as OA;

/**
 * @OA\Get(
 *     path="/tasks",
 *     summary="Получить список всех задач",
 *     @OA\Response(
 *         response=200,
 *         description="Успешный ответ",
 *         @OA\JsonContent(
 *             type="array",
 *             @OA\Items(ref="#/components/schemas/Task")
 *         )
 *     )
 * )
 */
function getTasks() {
    $tasks = [
        ['id' => 1, 'title' => 'Купить молоко', 'completed' => false],
        ['id' => 2, 'title' => 'Написать статью', 'completed' => true]
    ];
    header('Content-Type: application/json');
    echo json_encode($tasks);
}

/**
 * @OA\Post(
 *     path="/tasks",
 *     summary="Создать новую задачу",
 *     @OA\RequestBody(
 *         required=true,
 *         @OA\JsonContent(ref="#/components/schemas/TaskInput")
 *     ),
 *     @OA\Response(
 *         response=201,
 *         description="Задача создана",
 *         @OA\JsonContent(ref="#/components/schemas/Task")
 *     )
 * )
 */
function createTask() {
    // Логика создания задачи
    echo json_encode(['id' => 3, 'title' => 'Новая задача', 'completed' => false]);
}

/**
 * @OA\Schema(
 *     schema="Task",
 *     @OA\Property(property="id", type="integer"),
 *     @OA\Property(property="title", type="string"),
 *     @OA\Property(property="completed", type="boolean")
 * )
 * @OA\Schema(
 *     schema="TaskInput",
 *     @OA\Property(property="title", type="string"),
 *     @OA\Property(property="completed", type="boolean")
 * )
 */

// Простая маршрутизация
$uri = $_SERVER['REQUEST_URI'];
$method = $_SERVER['REQUEST_METHOD'];

if ($uri === '/tasks' && $method === 'GET') {
    getTasks();
} elseif ($uri === '/tasks' && $method === 'POST') {
    createTask();
}
?>

Шаг 2: Создайте скрипт для генерации документации generate-docs.php:

<?php
require_once 'vendor/autoload.php';

use OpenApi\Generator;

// Указываем директорию с исходным кодом
$openapi = Generator::scan(['.']);

// Сохраняем в JSON файл
file_put_contents('swagger.json', $openapi->toJson());

echo "Документация сгенерирована в файл swagger.json\n";
?>

Шаг 3: Запустите генерацию:

php generate-docs.php

После выполнения в корневой папке появится файл swagger.json с полной спецификацией вашего API.

Шаг 4: Запустите Swagger UI для визуализации:

Скачайте Swagger UI и укажите в настройках путь к вашему swagger.json файлу. Или используйте онлайн-редактор Swagger (editor.swagger.io), загрузив туда сгенерированный JSON.

Основные методы и функции Swagger-PHP

Swagger-PHP использует аннотации PHPDoc для описания API. Вот основные аннотации (методы), которые вам понадобятся:

1. @OA\Info

Что делает: Описывает метаданные API: название, версию, описание. Обязательная аннотация.

Параметры:

• title (string) — название API
• version (string) — версия API
• description (string) — описание
• termsOfService (string) — ссылка на условия использования
• contact (object) — контактная информация
• license (object) — информация о лицензии

Пример:

/**
 * @OA\Info(
 *     title="My API",
 *     version="1.0.0",
 *     description="Это мой первый API",
 *     @OA\Contact(
 *         email="admin@example.com"
 *     ),
 *     @OA\License(
 *         name="MIT",
 *         url="https://opensource.org/licenses/MIT"
 *     )
 * )
 */

2. @OA\Server

Что делает: Указывает базовый URL сервера, где развернут API.

Параметры:

• url (string) — URL сервера
• description (string) — описание сервера

Пример:

/**
 * @OA\Server(
 *     url="https://api.example.com/v1",
 *     description="Продакшн сервер"
 * )
 * @OA\Server(
 *     url="http://localhost:8000",
 *     description="Локальный сервер для разработки"
 * )
 */

3. @OA\Get, @OA\Post, @OA\Put, @OA\Delete, @OA\Patch

Что делает: Описывают HTTP методы эндпоинтов. Это основные аннотации для каждого маршрута.

Параметры:

• path (string) — URL путь
• summary (string) — краткое описание
• description (string) — подробное описание
• operationId (string) — уникальный идентификатор операции
• tags (array) — теги для группировки
• @OA\Response — описание ответа
• @OA\RequestBody — описание тела запроса
• @OA\Parameter — параметры запроса

Пример:

/**
 * @OA\Get(
 *     path="/users/{id}",
 *     summary="Получить пользователя по ID",
 *     tags={"Users"},
 *     @OA\Parameter(
 *         name="id",
 *         in="path",
 *         required=true,
 *         @OA\Schema(type="integer")
 *     ),
 *     @OA\Response(
 *         response=200,
 *         description="Успешный ответ",
 *         @OA\JsonContent(ref="#/components/schemas/User")
 *     ),
 *     @OA\Response(
 *         response=404,
 *         description="Пользователь не найден"
 *     )
 * )
 */

4. @OA\Parameter

Что делает: Описывает параметры запроса (path, query, header, cookie).

Параметры:

• name (string) — имя параметра
• in (string) — расположение: "path", "query", "header", "cookie"
• required (boolean) — обязательный ли параметр
• description (string) — описание
• @OA\Schema — схема данных параметра
• example (mixed) — пример значения

Пример:

/**
 * @OA\Parameter(
 *     name="page",
 *     in="query",
 *     description="Номер страницы для пагинации",
 *     required=false,
 *     @OA\Schema(type="integer", default=1),
 *     example=1
 * )
 */

5. @OA\RequestBody

Что делает: Описывает тело запроса для POST, PUT, PATCH методов.

Параметры:

• required (boolean) — обязательно ли тело запроса
• description (string) — описание
• @OA\MediaType или @OA\JsonContent — описание содержимого

Пример:

/**
 * @OA\RequestBody(
 *     required=true,
 *     description="Данные для создания пользователя",
 *     @OA\JsonContent(
 *         required={"name", "email"},
 *         @OA\Property(property="name", type="string", example="Иван"),
 *         @OA\Property(property="email", type="string", format="email", example="ivan@example.com"),
 *         @OA\Property(property="age", type="integer", example=25)
 *     )
 * )
 */

6. @OA\Response

Что делает: Описывает возможные ответы от эндпоинта.

Параметры:

• response (int/string) — HTTP статус код (200, 404, "default")
• description (string) — описание ответа
• @OA\JsonContent или @OA\MediaType — содержимое ответа
• @OA\Header — заголовки ответа

Пример:

/**
 * @OA\Response(
 *     response=200,
 *     description="Успешное получение списка пользователей",
 *     @OA\JsonContent(
 *         type="array",
 *         @OA\Items(ref="#/components/schemas/User")
 *     )
 * )
 * @OA\Response(
 *     response=401,
 *     description="Не авторизован"
 * )
 */

7. @OA\Schema

Что делает: Определяет модель данных (схему), которую можно переиспользовать в разных местах.

Параметры:

• schema (string) — имя схемы
• @OA