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

Сопровождал и генерировал документацию для REST API.

Основной подход, с которым работал в Laravel-проектах:

• описание endpoint-ов рядом с кодом;
• документирование параметров, ответов и ошибок;
• поддержка примеров запросов;
• генерация интерактивной API-документации.

Scribe

Использовал Laravel Scribe для документирования API.

• генерация интерактивной документации по реальным маршрутам приложения;
• извлечение описаний из контроллеров, PHPDoc и route metadata;
• работа с описаниями запросов через form requests и примерами параметров;
• единое место для описания endpoint-ов, параметров и примеров ответов;
• публикация API-документации как отдельной части проекта;
• генерация связанных артефактов для команды и интеграторов: Postman collection и OpenAPI spec.

Что обычно документировал

В API-документации обычно фиксировал:

• назначение endpoint-а;
• способ аутентификации;
• query/body параметры;
• структуру успешных ответов;
• ошибки и статус-коды;
• примеры авторизованных и неавторизованных сценариев;
• особенности retry, rate limiting и других инфраструктурных ограничений;
• примеры запросов для frontend или интеграторов.

См. также

• Документация проекта
• API
• Laravel: авторизация, API и real-time