Как использовать laravel-request-docs для документирования API в Laravel

Laravel — это мощный PHP-фреймворк, который упрощает разработку веб-приложений. Одним из ключевых аспектов разработки на Laravel является обработка HTTP-запросов. Для документирования API в Laravel часто используется пакет laravel-request-docs. Этот пакет представляет собой простой инструмент для документирования API, который является альтернативой Swagger и поддерживает OpenAPI. Он позволяет автоматически генерировать документацию для ваших запросов, что значительно упрощает процесс разработки и поддержки кода.

В этой статье мы рассмотрим, как использовать laravel-request-docs для документирования API в Laravel, а также как его использовать совместно с пакетом mezatsong/laravel-swagger-docs.

Установка

Первым шагом является установка пакета laravel-request-docs. Вы можете сделать это с помощью Composer:

composer require --dev laravel-request-docs

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

php artisan vendor:publish --provider="LaravelRequestDocs\LaravelRequestDocsServiceProvider"

Эта команда создаст файл конфигурации laravel-request-docs.php в директории config.

Конфигурация

После публикации конфигурационного файла, вы можете настроить его под свои нужды. Основные параметры конфигурации включают:

output_path: Путь, по которому будет сохранена сгенерированная документация.
title: Заголовок документации.
description: Описание документации.
routes: Массив маршрутов, для которых будет генерироваться документация.

Пример конфигурационного файла:

return [
    'output_path' => public_path('docs'),
    'title' => 'API Documentation',
    'description' => 'Documentation for the API endpoints',
    'routes' => [
        'api/*',
    ],
];

Генерация документации

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

php artisan laravel-request-docs:export

Эта команда проанализирует ваши маршруты и запросы, а затем сгенерирует документацию в указанном вами пути.

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

Сгенерированная документация будет содержать следующие разделы:

Общая информация: Заголовок и описание документации.
Маршруты: Список всех маршрутов, для которых была сгенерирована документация.
Запросы: Детальная информация о каждом запросе, включая метод, URL, параметры, заголовки и примеры ответов.

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

Рассмотрим пример использования laravel-request-docs на практике. Допустим, у вас есть следующий маршрут в вашем приложении:

Route::get('/api/users', [UserController::class, 'index']);

В контроллере UserController у вас есть метод index, который возвращает список пользователей:

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class UserController extends Controller
{
    /**
     * Get a list of users.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return \Illuminate\Http\JsonResponse
     */
    public function index(Request $request)
    {
        // Логика получения пользователей
        return response()->json([
            'users' => [
                ['id' => 1, 'name' => 'John Doe'],
                ['id' => 2, 'name' => 'Jane Doe'],
            ],
        ]);
    }
}

В этом примере используется PHPDoc-комментарий для метода index, который описывает, что делает этот метод. Это поможет laravel-request-docs создать более подробную документацию.

После настройки конфигурационного файла и генерации документации, вы получите документацию, которая будет содержать информацию о маршруте /api/users, включая метод, параметры и примеры ответов.

Использование совместно с mezatsong/laravel-swagger-docs

Если вы уже используете пакет mezatsong/laravel-swagger-docs для генерации документации Swagger, вы можете использовать laravel-request-docs для дополнения или альтернативной генерации документации. Для этого просто установите оба пакета и настройте их конфигурационные файлы.

Features

laravel-request-docs предлагает множество функций, которые делают его мощным инструментом для документирования API:

Light and Dark mode: Поддержка светлой и темной тем для удобства чтения.
Automatic rules fetching from injected Request and by regexp: Автоматическое извлечение правил из введенных запросов и с помощью регулярных выражений.
Automatic routes fetching from Laravel Routes: Автоматическое извлечение маршрутов из Laravel.
Support for Laravel logs: Поддержка логов Laravel.
Support for SQL query and query time: Поддержка SQL-запросов и времени их выполнения.
Support for HTTP response time and memory consumption: Поддержка времени ответа HTTP и потребления памяти.
Support for Authorization Headers: Поддержка заголовков авторизации.
Support for File uploads: Поддержка загрузки файлов.
Support for Eloquents events: Поддержка событий Eloquent.
Display extra documentation using markdown: Возможность отображения дополнительной документации с использованием Markdown.
Saves history previous requests: Сохранение истории предыдущих запросов.
Added filters to sort, group and filter routes by methods, controllers, middlewares, routes: Добавлены фильтры для сортировки, группировки и фильтрации маршрутов по методам, контроллерам, посредникам и маршрутам.
Export Laravel API, routes, rules and documentation to Postman and OpenAPI 3.0.0: Экспорт Laravel API, маршрутов, правил и документации в Postman и OpenAPI 3.0.0.

Скриншоты

Для лучшего понимания, вот несколько скриншотов из официальной документации:

Темный и светлый режимы

Использует локальное хранилище для сохранения истории предыдущих запросов и заголовков запросов.
Хронология запросов, SQL, ответов и событий ниже:

Настройки для сортировки, группировки и фильтрации

Заключение

laravel-request-docs — это мощный и простой инструмент для документирования API в Laravel. Он поддерживает OpenAPI и может быть использован как альтернатива Swagger. С помощью этого пакета вы можете сосредоточиться на написании кода, а не на его документировании.

Если вы хотите узнать больше о возможностях laravel-request-docs, посетите официальную документацию пакета.