Представьте что у вас команда специалистов, которая по принципу code-first делает систему с множеством бизнес-историй на базе микросервисов. Все люди опытные, всем есть что делать кроме того как писать документации или спецификации на разработанный API. И все изначально знают, что если захотел использовать какой сервис, то надо заглянуть в код и потом спросить в общем чате если что непонятно. Знакомая ситуация не так ли? -))) И в целом все нормально, если бы со временем не росла команда, не росло количество сервисов и функций, не появлялись баги от бизнеса и тестеров, не требовалось предоставлять API для интеграции смежным командам...
Эта статья, на момент написания, является моим личным мнением о минимальной структуре документирования микросервисов в условиях его отсутствия. Личное мнение родилось в ходе мозгового штурма реальной ситуации и поисков повышения качества в разработке среднего по масштабу бизнес приложения.