Pull to refresh
3
0
Send message

Система автоматического документирования REST-API в Laravel проектах

Reading time 8 min
Views 23K

Преамбула


Для того, чтоб описать и задокументировать правила клиент-серверного
взаимодействия используя Rest-api можно выделить три основных метода:


  1. Описывать своим коллегам правила обращения к серверу на пальцах
    Этот метод быстр и не требует долгосрочной поддержки, но высока вероятность, что вас за это будут бить.
  2. Руками составлять Google-docs/Wiki/Readme в проекте
    Удобно тем, что однажды написанная документация не требует повторного объяснения. Её можно показать коллегам и даже иногда заказчику. Минусом данного метода является долгосрочная поддержка такой документации. Когда Api в проекте вырастает до таких размеров, что сама мысль "А когда же я обновлял документацию?" вызывает холодок по спине, тогда вы понимаете, что дальше так продолжаться не может. Формально вы можете обновлять документацию очень часто и маленькими фиксами, но это до первого отпуска.
  3. Использовать систему автодокументирования
    И вот для того, чтобы решить минусы первых двух методов человечество придумало системы автоматического документирования. Основная идея заключается в том, что к проекту пристыковывается некий плагин, который собирает информацию по вашему коду, сам составляет документацию и обёртывает её в удобочитаемый формат. Но большинство решений по этому методу не идеальны. Давайте попробуем сделать инструмент, который поможет получить документацию нашего проекта с минимальным количеством телодвижений

Читать дальше →
Total votes 14: ↑14 and ↓0 +14
Comments 6

Information

Rating
Does not participate
Registered
Activity