PhpLightDoc

Создавайте API документацию без усилий

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

К документации Установка

Почему PhpLightDoc?

Простота и скорость вместо сложности и затрат.

Проблема Swagger

Устали писать многословные YAML или бесконечные аннотации? Swagger мощный, но часто требует значительных ручных усилий и усложняет код.

PhpLightDoc

PhpLightDoc находит золотую середину. Это бесплатный open-source пакет, который автоматически генерирует документацию, требуя лишь минимальных и интуитивно понятных PHP 8 атрибутов или комментариев.

Платные Инструменты

Инструменты вроде Scramble предлагают отличную автоматизацию, но имеют свою цену. Это может быть барьером для инди-разработчиков и небольших проектов.

Быстрый старт

Начните работу за пару минут.

1. Установите пакет через Composer

composer require wfgm5k2d/php-light-doc

2. Опубликуйте конфигурацию и шаблоны

php artisan vendor:publish --provider='Wfgm5k2d\PhpLightDoc\Providers\PhpLightDocServiceProvider'

3. Настройте .env файл

# Ваш путь к файлу документации
PATH_TO_FILE_DOCUMENTATION='/your_full_path_to_file/api_documentation.json'
# Папки для сканирования (через запятую)
PATH_TO_DIR_SCAN='app/Domain,app/Http/Controllers'
# Папки для исключения (через запятую)
PATH_TO_DIR_EXCLUDE='app/Http/Controllers/Admin,CustomBackupController'

4. Сгенерируйте документацию

Запустите команду, и ваша документация будет доступна по адресу /doc.

php artisan doc:generate

Документация

Используйте простые PHP 8 атрибуты или комментарии для обогащения вашей документации.

Группировка контроллеров

Структурируйте вашу документацию, объединяя контроллеры в логические группы.

Через комментарий
// group Пользователи
final class UserController extends Controller
Через атрибут (рекомендуется)
#[DocGName('Пользователи')]
final class UserController extends Controller

Расширенная группировка

Для создания более сложной иерархии вы можете объединять группы контроллеров в одну большую категорию. Для этого передайте второй параметр в атрибут DocGName.

Через атрибут (рекомендуется)
// Этот контроллер попадет в подгруппу "User API" внутри основной группы "Пользователи"
#[DocGName('User API', 'Пользователи')]
final class UserController extends Controller {}

// Этот контроллер попадет в подгруппу "Auth" внутри той же основной группы
#[DocGName('Auth', 'Пользователи')]
final class AuthController extends Controller {}

Названия роутов

Дайте вашим API-эндпоинтам понятные человеку имена для легкой идентификации.

Через комментарий
// name Создать заявку на компенсацию
public function createApplication(Request $request): JsonResponse
Через атрибут (рекомендуется)
#[DocRName('Создать заявку на компенсацию')]
public function createApplication(Request $request): JsonResponse

Требования Middleware

Укажите требования к авторизации или другие кастомные заголовки прямо в документации.

Через комментарий
// middleware-name Требуется аутентификация
// middleware-value Authorization: Bearer {token}
final class SecureController extends Controller
Через атрибут (рекомендуется)
#[DocMiddleware('Требуется аутентификация', 'Authorization: Bearer {token}')]
final class SecureController extends Controller

Коды ответов

Пакет автоматически определяет коды ответов из вашего кода, но вы также можете указать их вручную.

Через комментарий
// response-codes 200 404 500
public function getUserData(Request $request): JsonResponse
Через атрибут (рекомендуется)
#[DocResponseCodes([200, 404, 500])]
public function getUserData(Request $request): JsonResponse

Внесите свой вклад

Библиотека находится в активной разработке. Если у вас есть идеи для улучшения, исправления ошибок или новые функции, мы с радостью будем ждать ваши pull request!

Предложить Pull Request