wfgm5k2d/phplightdoc

Creating auto-documentation

Maintainers

Details

github.com/wfgm5k2d/php-light-doc

Homepage

Source

Issues

Installs: 9

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 1

Forks: 0

Open Issues: 0

1.0.6 2025-04-08 06:49 UTC

Requires

MIT 93966e36e44fb626f24ad810b7ec9ecc191e2f4a

laravelPhpLightDoc

This package is auto-updated.

Last update: 2025-04-08 06:50:11 UTC

README

Laravel API Docs

Этот пакет автоматически анализирует контроллеры и маршруты Laravel, извлекая информацию о группах, именах, middleware, кодах ответов и формируя удобную документацию в формате JSON.

📦 Установка

composer require wfgm5k2d/php-light-doc

📦 Опубликуйте все файлы

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

Настройте переменные окружения

# Ваш путь до файла с документацией
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'

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

После установки в Laravel появится команда для генерации документации:

php artisan api-docs:generate

Документация будет сохранена в корне проекта /api_documentation.json и доступна в браузере по маршруту /doc.

📝 Аннотации и атрибуты

Вы можете дополнительно аннотировать контроллеры и методы для более точного описания API.

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

Группы помогают структурировать документацию по тематическим разделам. Вы можете дать название группе контроллера. По умолчанию название не указывается img_1.png

Вы можете добавить название группы

Через комментарий:

// group Пользователи
final class UserController extends Controller

Или атрибут:

#[DocGName('Пользователи')]
final class UserController extends Controller

img_2.png

Описание маршрутов

По умолчанию названия у роута нет img_3.png но вы можете задать понятное название маршруту:

Через комментарий:

// name Создать заявку на компенсацию
public function createApplication(Request $request): JsonResponse

Или атрибут:

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

img_4.png

Требования middleware

Если метод требует авторизации или специальных заголовков, укажите это явно.

Через комментарий:

// middleware-name Требуется аутентификация
// middleware-value Authorization: Bearer {token}
final class SecureController extends Controller

Или атрибут:

#[DocMiddlewareName('Требуется аутентификация', 'Authorization: Bearer {token}')]
final class SecureController extends Controller

img_5.png

По умолчанию проверяется такой набор middleware

auth
throttle
can
requires

Коды ответов

По умолчанию код ответа будет 200 если не указано других. Пакет ищет коды ответов в таких конструкциях:

return response()->json()
return new JsonResponse([])
return new JsonResponse([], Response::HTTP_...)
return new JsonResponse([], 200)

Вы можете самостоятельно указать доступные коды ответов если они не определились

Через комментарий:

// response-codes 200 404 500
public function getUserData(Request $request): JsonResponse

Или атрибут:

#[DocResponseCodes([200, 404, 500])]
public function getUserData(Request $request): JsonResponse

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

Запустите команду генерации:

php artisan api-docs:generate

Откройте /doc в браузере для просмотра.

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

Этот пакет упрощает процесс документирования API, обеспечивая структурированный и удобочитаемый формат данных. 🚀

Этот код включает:

  • Красивые badges в шапке
  • Четкое разделение на секции
  • Подсветку кода с указанием языков
  • Эмодзи для визуального выделения разделов
  • Хорошую читаемость и структуру
  • Выделение важной информации (например, команды)