Как документировать Webhooks в Apiary/API Blueprint

Question

Я только начинаю с api blueprint, используя apiary для создания документов для нашего api. У нас есть и REST API, и несколько веб-хуков. API REST достаточно прост в создании, но я не могу понять, как лучше всего создать документацию для веб-хуков.

Мы хотели бы поделиться структурами данных между нашими веб-хуками и REST API.

Пока что единственное, о чем я могу думать, это документировать webhooks, как ресурс REST. Это кажется немного странным, так как обычно документация webhook - это просто информация о полезной нагрузке, но, возможно, это лучший вариант.

Кто-нибудь делает это? Или, может быть, есть лучшие инструменты для этого?

В конечном счете, хотелось бы что-то вроде того, что делает github: https://developer.github.com/webhooks/

Answer 1

Даже если у APIBlueprint нет встроенной конструкции для документирования webhook, помните, что вы всегда можете использовать уценку для описания ваших конечных точек.

С этой "силой" вы сможете выражать все свои мысли.

Если вы посмотрите на MovieDb Api, вы можете увидеть, как они используют таблицы уценки для выражения того, что, вероятно, не совсем соответствует самому языку ApiBlueprint.

Надеюсь, это поможет!

V.