Swagger/OpenAPI генерация для PHP

Swagger/OpenAPI генерация для PHP: Полный обзор инструментов

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

Что такое Swagger/OpenAPI?

OpenAPI Specification (OAS) — это спецификация, определяющая стандарт описания REST API в формате JSON или YAML. Она позволяет:

Автоматически генерировать интерактивную документацию (Swagger UI);
Создавать клиентские библиотеки для различных языков программирования;
Проверять корректность запросов и ответов;
Интегрироваться с CI/CD пайплайнами.

Основные библиотеки для PHP

Для работы с OpenAPI в PHP существует несколько популярных библиотек. Рассмотрим каждую из них подробнее.

1. Swagger-PHP (zircote/swagger-php)

Это наиболее популярная и зрелая библиотека для генерации OpenAPI спецификации из аннотаций PHP. Она позволяет описывать API прямо в коде, что упрощает поддержку документации в актуальном состоянии.

Установка:

composer require zircote/swagger-php

Пример использования:

<?php
use OpenApi\Annotations as OA;

/**
 * @OA\Info(
 *     title="Мой API",
 *     version="1.0.0",
 *     description="Пример API для демонстрации Swagger"
 * )
 * @OA\Server(
 *     url="https://api.example.com",
 *     description="Production server"
 * )
 */
class UserController
{
    /**
     * @OA\Get(
     *     path="/api/users",
     *     summary="Получить список пользователей",
     *     @OA\Response(
     *         response=200,
     *         description="Успешный ответ",
     *         @OA\JsonContent(type="array",
     *             @OA\Items(ref="#/components/schemas/User")
     *         )
     *     )
     * )
     */
    public function getUsers()
    {
        // Логика получения пользователей
    }

    /**
     * @OA\Schema(
     *     schema="User",
     *     type="object",
     *     @OA\Property(property="id", type="integer"),
     *     @OA\Property(property="name", type="string"),
     *     @OA\Property(property="email", type="string")
     * )
     */
    public function userSchema()
    {
        // Пустой метод для описания схемы
    }
}

// Генерация спецификации
$openapi = \OpenApi\Generator::scan(['/path/to/controllers']);
file_put_contents('openapi.json', $openapi->toJson());
?>

2. OpenAPI-Server (thecodingmachine/openapi-server)

Эта библиотека позволяет не только описывать API, но и автоматически генерировать серверный код на основе OpenAPI спецификации. Она особенно полезна при использовании принципа Design-First разработки.

Установка:

composer require thecodingmachine/openapi-server

Пример генерации сервера:

<?php
use TheCodingMachine\OpenAPI\Server\Builder;

// Загрузка спецификации
$spec = json_decode(file_get_contents('openapi.json'), true);

// Создание сервера
$builder = new Builder();
$server = $builder->build($spec, 'App\\Controllers\\');

// Обработка запроса
$response = $server->handle($request);
?>

3. Swagger-UI для PHP

Для отображения интерактивной документации можно использовать встроенный Swagger UI. Существует несколько способов интеграции:

Использование CDN: Подключите CSS и JS файлы Swagger UI напрямую;
Локальная установка: Скачайте пакет swagger-ui-dist;
Через PHP библиотеку: Используйте darkaonline/swagger-ui.

Пример простой интеграции:

<!DOCTYPE html>
<html>
<head>
    <title>Документация API</title>
    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css">
</head>
<body>
    <div id="swagger-ui"></div>
    <script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
    <script>
        SwaggerUIBundle({
            url: "/openapi.json",
            dom_id: '#swagger-ui',
        });
    </script>
</body>
</html>