Я напишу понятную документацию API, которой ваши разработчики смогут следовать с первого дня

Почему большинство документов API терпят неудачу

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

Как я это пишу

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

Что содержит документация

• Аутентификация: получение токена, его обновление и что происходит, когда он истекает в середине сеанса.
• Каждая конечная точка с параметрами, полный пример запроса и реальная форма ответа.
• Справочник по ошибкам, который сопоставляет каждый код ошибки с причиной и исправлением, а не просто повторяет сообщение.
• Путь к началу работы, который позволяет новому разработчику перейти от нуля к успешному вызову менее чем за десять минут.
• Ограничения скорости, пагинация, веб-хуки и идемпотентность объясняются там, где они действительно применимы.

Формат

Markdown в вашем репозитории, структурированный для OpenAPI или сайта документации — что бы вы ни собирались поддерживать. Примеры кода на языках, о которых спрашивают ваши пользователи, проверенные путем их выполнения. Коллекция Postman или аналогичная включена, если вы хотите.

Что мне нужно

Доступ к репозиторию или файл OpenAPI, одна рабочая учетная запись для тестовой среды и любые вопросы, на которые ваша служба поддержки устала отвечать. Эти вопросы — это план.

Не включено

Маркетинговый текст. Это точно документирует, что делает программное обеспечение; целевая страница — это другое ремесло.

Сроки выполнения и общение

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