Автоматическое посторение документации.

Это бязательный процесс даже для процесса самой разработки. Допустим у нас будет 500 методов в апи. Иногда нужно будет посмотреть и вспомнить что куда передается и что получается. Так же для сторонних разработчиков, это будет полезно.

Структура метоодов 3 уровня

Модуль
`--Группа
  `-- Метод

Все лежат в папках ИмяМодуля/Api/ИмяГруппы/Метод.api.json.

В файле json есть все что нужно. Это описание метода, список выдаваемых ошибок, список передаваемых параметров, даже фильтры и валидация.

Для использования документации можно создать новый роут http:://domain/docs. У Slim есть возможность генерить страницы и там есть вьюшки. Всего то нужна одна страница и там уже красивую навигацию. Типа того что ты сделал с картой на тайге. Жмешь метод и появлется его описание.

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

В дополнение каждый модуль имеет meta.json где содержится описание и имя самого модуля. От туда можно взять данные для формирования главной страници модуля.

Comments (8)