ВоITи и выITи

  Intro Существует множество подходов написания API документации, и большинство из них автоматизированные: от сбора XML комментариев из кода до создания API из документации с ноля в Swagger или таких инструментах, как Stoplight . Но я бы хотел сделать шаг назад и посмотреть на «картину» в целом, то есть сконцентрироваться не на том КАК мы создаём документацию, а всё-таки ЧТО мы в ней предоставляем. Смотрите шире Последние 8 лет я являюсь разработчиком API и потребителем API одновременно. Мне приходилось реализовывать интеграцию одних продуктов в другие через API множество раз: интеграция с ГИС, интеграция поиска и бронирования тревел-услуг, интеграция множества всевозможных ФинТех сервисов, и т.д. Всего я видел не менее 200 различных документаций публичного API и не менее 100 из них мне приходилось непосредственно использовать. Я видел много способов описания API: Описания в виде 5 двухсот-страничных PDF документов, каждый из которых в деталях описывал