Swagger/OpenAPI генерация для PHP: лучшие инструменты и библиотеки

Swagger/OpenAPI генерация для PHP: автоматизация документирования API

Swagger (теперь OpenAPI) — это стандарт описания RESTful API, который позволяет разработчикам, клиентам и автоматизированным инструментам понимать возможности сервиса без доступа к исходному коду. Для PHP-разработчиков ключевым инструментом является библиотека zircote/swagger-php (ранее известная как swagger-php), которая автоматически генерирует OpenAPI-спецификацию из аннотаций в коде.

Что такое zircote/swagger-php?

Это основная библиотека для генерации OpenAPI спецификаций в PHP. Она анализирует PHPDoc-аннотации в контроллерах, моделях и маршрутах, создавая JSON/YAML файл, который можно использовать для:

• Автоматической генерации документации (Swagger UI, ReDoc)
• Генерации клиентских библиотек для различных языков
• Тестирования API (Postman, Insomnia)
• Валидации запросов и ответов

Установка и настройка

Установка через Composer:

composer require zircote/swagger-php

Минимальная конфигурация для Laravel (или любого фреймворка) включает создание аннотаций в контроллере. Пример простого контроллера с OpenAPI-аннотациями:

<?php

namespace App\Http\Controllers\Api;

use OpenApi\Annotations as OA;

/**
 * @OA\Info(title="My API", version="1.0.0")
 * @OA\Server(url="https://api.example.com")
 */
class UserController extends Controller
{
    /**
     * @OA\Get(
     *     path="/api/users/{id}",
     *     summary="Получить пользователя по ID",
     *     @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="Пользователь не найден")
     * )
     */
    public function show($id)
    {
        // логика
    }
}

Генерация спецификации

Для создания файла OpenAPI выполните команду:

vendor/bin/openapi src -o public/openapi.yaml

Или используйте PHP-код:

<?php

use OpenApi\Generator;

$openapi = Generator::scan(['/path/to/project/src']);
file_put_contents('public/openapi.json', $openapi->toJson());

Продвинутые возможности

Библиотека поддерживает:

• Вложенные схемы — автоматическое создание моделей из аннотаций
• Группировку эндпоинтов через @OA\Tag
• Безопасность — @OA\SecurityScheme для JWT, OAuth2
• Примеры запросов — @OA\RequestBody с примерами

Пример модели с аннотациями:

<?php

/**
 * @OA\Schema(
 *     schema="User",
 *     required={"id", "email"},
 *     @OA\Property(property="id", type="integer", format="int64"),
 *     @OA\Property(property="email", type="string", format="email"),
 *     @OA\Property(property="name", type="string"),
 *     @OA\Property(property="created_at", type="string", format="date-time")
 * )
 */
class User
{
    // свойства
}

Интеграция с фреймворками

Для Laravel существует пакет darkaonline/l5-swagger, который добавляет:

• Автоматическую генерацию при каждом запросе
• Встроенный Swagger UI
• Конфигурацию через config файл

Установка:

composer require darkaonline/l5-swagger
php artisan vendor:publish --provider="L5Swagger\L5SwaggerServiceProvider"

Для Symfony используйте nelmio/api-doc-bundle.

Сравнение с альтернативами

Инструмент	Особенности	Когда использовать
zircote/swagger-php	Аннотации, минимальная конфигурация	Для проектов без фреймворка или с кастомной архитектурой
darkaonline/l5-swagger	Готовая интеграция с Laravel	Для проектов на Laravel
nelmio/api-doc-bundle	Глубокая Также в библиотеке Passlib – хэширование паролей Joi для JavaScript (Node.js): полное руководство с примерами Работа с CSV в C# (.NET): библиотеки и примеры Работа с Excel в Kotlin: библиотеки Apache POI и Kotlin-обертки ORM для JavaScript (Node.js): сравнение Sequelize, TypeORM, Prisma Рекомендаций Работа с CSV в C# (.NET): библиотеки и примеры Машинное обучение на C# (.NET): обзор библиотек и инструментов Swagger/OpenAPI генерация для Go (Golang): полное руководство Машинное обучение на Java: обзор основных библиотек для разработки 🍪 Сначала примите условия Чтобы войти на сайт, необходимо принять соглашение об использовании файлов cookie. Мы используем их для авторизации и улучшения работы сайта. Политика конфиденциальности Принять и продолжить Закрыть 🍪 Мы используем файлы cookie для авторизации, аналитики и улучшения работы сайта. Продолжая пользоваться сайтом, вы соглашаетесь с нашей политикой конфиденциальности. Принять Только необходимые