Как создать хорошую документацию к API?

Казалось бы, очевидный вопрос, особенно когда клепаешь доку каждый день на автомате. Тем удивительнее, скольких аналитиков волнует эта тема. Сегодня разбираем, что должно быть в хорошей документации к API.

Как обычно, все субъективно, но на мой взгляд в API документе содержатся следующие разделы:

1) История изменений
2) Оглавление
3) Системная информация
4) Алгоритм работы
5) Примеры

История изменений. Здесь все просто, ключевая цель раздела - найти того, кто создавал доку или вносил в нее какие-либо изменения. Обычно делаю в виде таблице с колонками: дата изменения, описание изменений, связанная задача, автор изменений. Если в компании используется Jira/Confluense, связка задачи и доки будет отражаться сразу в обоих местах.

Оглавление. Для быстрой навигации по разделам документа. В конфе можно настроить автоматически.

Системная информация. Или «нефункциональные требования». Например, требования к аутентификации, порядок ретраев и таймаутов, тип входного и выходного объекта (если описываете адаптер, на вход может прийти XML, а на выходе JSON), название очереди. В общем указывается вся важная информация, которая не относится к алгоритму работы напрямую.

Алгоритм работы. Самое важное. По шагам расписываем, как работает тот или иной метод. Указываем откуда приходит сообщение (из очереди или из внешней системы или по триггеру и тд), прикладываем пример входящего сообщения. Далее описываем что мы делаем с этим сообщением: раскладываем в базу, преобразуем, формируем новый запрос и тд. Допустим, мы формируем новый запрос, тогда прикладываем его пример в формате curl, указываем метод HTTP и url, а также подробно описываем параметры запроса.

Для описания параметров запроса обычно использую таблицу со следующими колонками: название параметра, описание параметра, пример, тип данных, обязательность, маппинг, дополнительные комментарии.

Затем описываем ответ, алгоритм тот же: прикладываем пример ответа и подробное описание параметров ответа.

Наконец, если требуется обработать ответ, то указываем, как мы его обрабатываем: записываем в поля таблицы или формируем новое сообщение или отправляем в очередь и тд.

Примеры. Их можно указывать отдельно в конце или по ходу выполнения алгоритма, как я написал выше. Примеры очень важны! Они сильно упрощают работу разработчикам и тестировщикам.

Может показаться, что описание слишком подробное и пошаговое, но таким образом нас понимают несколько групп пользователей. Разработчики видят техническую информацию и понимают как им работать, тестировщики могут быстро кидать примеры и проверять работоспособность, бизнес понимает, как работает сервис, другие аналитики смогут без проблем разобраться в текущей документации. И все в плюсе.

В качестве бонуса, для технического описания API я бы не стал придумывать велосипед и просто использовать формат OpenAPI. Нашел ультимативный гайд, где подробно описано как документировать API.

Если наберем 25 реакций, скину пример своей документации из практики)

#база