Здравствуйте!

В этой статье мы расскажем, как интегрировать Swagger UI в ваше приложение Laravel, чтобы вы могли легко просматривать и взаимодействовать с вашим Swagger (OpenAPI v3) файлом прямо в приложении. Swagger UI предоставляет удобный интерфейс для тестирования и документирования API, что значительно упрощает работу с API и его документацией.

Пакет Swagger UI для Laravel упрощает доступ к файлу Swagger (JSON или YAML OpenAPI v3) вашего проекта через интерфейс Swagger UI прямо в вашем приложении Laravel. Всё, что вам нужно сделать, это поместить файл OpenAPI в директорию resources/swagger/openapi.json (это можно настроить) и перейти по пути /swagger в локальной среде проекта.

Что мне особенно нравится в этом пакете, так это то, что он автоматически обновляет Swagger UI, чтобы использовать текущую среду проекта, включая установку базового URL API на базовый URL проекта Laravel. Пакет также позволяет настроить OAuth2, который можно интегрировать в Swagger UI через файл конфигурации пакета.

URL /swagger доступен локально, а также вы можете определить пользовательскую логику доступа для авторизации и управления доступом к Swagger UI в не локальных средах.

Установка

Для начала вам нужно установить пакет Swagger UI для Laravel с помощью Composer:

composer require nextapps/laravel-swagger-ui

После установки пакета выполните публикацию сервис-провайдера и файла конфигурации, используя команду Artisan:

php artisan swagger-ui:install

Использование

Swagger UI будет доступен по адресу /swagger. По умолчанию доступ к нему возможен только в локальной среде. В файле app/Providers/SwaggerUiServiceProvider.php находится метод gate, который контролирует доступ к Swagger UI в не локальных средах. Вы можете настроить этот метод для ограничения доступа к вашему Swagger UI и файлу Swagger (OpenAPI v3):

<?php
/**
 * Register the Swagger UI gate.
 *
 * This gate determines who can access Swagger UI in non-local environments.
 *
 * @return void
 */
protected function gate()
{
    Gate::define('viewSwaggerUI', function ($user = null) {
        return in_array(optional($user)->email, [
            //
        ]);
    });
}

В опубликованном файле config/swagger-ui.php вы можете настроить путь к Swagger UI и местоположение файла Swagger (OpenAPI v3). По умолчанию пакет ожидает найти файл OpenAPI в директории resources/swagger. Вы также можете указать URL, если файл OpenAPI не находится непосредственно в проекте Laravel. Здесь же можно определить несколько версий одного и того же API.

<?php
// в config/swagger-ui.php
return [
    // ...

    'path' => 'swagger',

    'versions' => [
        'v1' => resource_path('swagger/openapi.json')
    ],

    // ...
];

По умолчанию пакет будет настраивать URL сервера и URL OAuth в файле OpenAPI на базовый URL приложения Laravel. Это можно отключить в конфигурации.

<?php
// в config/swagger-ui.php

return [
    // ...

    'modify_file' => true,

    // ...
];

Вы также можете задать ID клиента OAuth и секрет клиента. Эти значения будут автоматически подставлены в форму аутентификации в Swagger UI.

<?php
// в config/swagger-ui.php

return [
    // ...

    'oauth' => [
        'token_path' => 'oauth/token',
        'refresh_path' => 'oauth/token',
        'authorization_path' => 'oauth/authorize',

        'client_id' => env('SWAGGER_UI_OAUTH_CLIENT_ID'),
        'client_secret' => env('SWAGGER_UI_OAUTH_CLIENT_SECRET'),
    ];

    // ...
];

Тестирование

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

composer test

Вы можете узнать больше об этом пакете, получить полные инструкции по установке и просмотреть исходный код на GitHub по адресу: nextapps-be/laravel-swagger-ui.

На этом всё! Теперь вы знаете, как добавить Swagger UI в ваше приложение Laravel и настроить его под свои нужды. Если у вас возникнут вопросы или потребуется дополнительная помощь, не стесняйтесь обращаться. Удачи в разработке!