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

Question

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

Мы хотели бы разделить Структуры данных между нашими веб-камерами и нашим REST api.

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

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

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

Answer 1

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

С этой «силой» вы должны быть способны выразить все свои мысли.

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

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

V.