Забавные размышления о трех стилях документирования API: описательном, в виде захватывающих историй(storytelling) и предписывающем. При случае, надо будет сделать пример с картинками https://caseysoftware.com/blog/three-styles-api-documentation (Keith Casey это автор учебного курса Designing RESTful APIs)