Можно ли вместо OpenAPI спецификации для описания интерфейсов использовать примеры запросов и команд? Посмотрите Jsight и дайте свой вариант ответа (внутри описание, примеры и видео, а вот ссылка на большой текст на медиуме: What’s Wrong With OpenAPI?)