Гайд по документированию запросов API с помощью Scramble

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

🔸 Автоматическая генерация
Scramble анализирует код и создает документацию на основе правил валидации, параметров маршрутов и обращений к $request. Например, параметры пути определяются по типу модели: integer или uuid.

🔹 Дополнение документации
К автоматически созданной структуре можно добавить описания, примеры и значения по умолчанию. Если Scramble пропустил параметр или его тип указан неверно, это легко исправить вручную.

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

🔹 Общие параметры для всех эндпоинтов
Если заголовки или куки используются во всех запросах, их можно задать один раз с помощью глобальных трансформеров, что сократит дублирование кода.

🔸 Аутентификация и безопасность
Документировать механизм авторизации можно с помощью трансформеров, а публичные эндпоинты помечать как не требующие аутентификации. Также Scramble позволяет автоматически убирать требование аутентификации для маршрутов без auth-middleware.

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

👉Читать статью

Библиотека пхпшника