Начните с контракта
У REST API-документации сразу две аудитории: машины и люди. Машиночитаемый контракт описывает пути, методы, параметры, схемы и ответы. Человеческая документация объясняет смысл, ограничения, сценарии и решения, которые должен принять разработчик. Нужны оба слоя.
Покажите успешный сценарий как запускаемую историю
Справочная страница должна позволить разработчику быстро выполнить первый успешный запрос. Покажите аутентификацию, полный request и полный response. Примеры должны быть валидными и реалистичными. Если поле обязательно только в определённом состоянии, объясните это рядом с полем.
Ошибки — часть интерфейса
Не заканчивайте документацию на 200. Опишите ошибки аутентификации, валидации, конфликты, лимиты и асинхронные состояния. Если продукт поддерживает стабильные идентификаторы ошибок, указывайте их и объясняйте следующий шаг клиента.
Разделяйте reference и guides
Reference отвечает «что существует?». Guide отвечает «как решить задачу?». Огромная endpoint-страница, которая одновременно обучает архитектуре, onboarding и troubleshooting, становится плохо сканируемой. Связывайте слои ссылками, но не смешивайте их.
Делайте примеры исполняемыми
Примеры устаревают быстрее прозы, потому что зависят от реального синтаксиса и состояния продукта. По возможности включайте типовые запросы в тесты или CI. Минимум — проверяйте JSON и соответствие схемам.
Считайте OpenAPI источником, а не всем интерфейсом
OpenAPI отлично подходит для генерации reference, mock server и валидации, но схема сама по себе не объясняет бизнес-смысл. Добавляйте концептуальные страницы, аутентификацию, жизненный цикл, лимиты и сквозные сценарии.
Хорошая API-документация позволяет разработчику предсказать поведение системы до первого вызова. Это более сильная цель, чем просто перечислить endpoints.
Практический разбор
Превратите «Как правильно документировать REST API» в одну законченную задачу разработчика. Возьмите вымышленный, но реалистичный ресурс — например отчёт, устройство или заказ — и опишите кратчайший путь от аутентификации до успешного результата. Включите запрос, важные поля ответа, одну вероятную ошибку и следующее действие после неё. Пример должен быть принципиально выполнимым даже без живого сервиса.
Проверьте его так, будто по нему действительно пишут клиент:
- какие значения разработчик обязан заменить;
- какие идентификаторы возвращает сервер и где они используются дальше;
- какой статус или поле подтверждает успех;
- что делать при ошибке credentials, входных данных или rate limit.
Если ответы разбросаны по несвязанным страницам, документация может быть формально полной, но практически слабой. Хорошая API-документация позволяет предсказать взаимодействие с системой, а не только узнать названия endpoint-ов.
Короткий редакционный чек-лист
- Начните с контракта. У REST API-документации сразу две аудитории: машины и люди.
- Покажите успешный сценарий как запускаемую историю. Справочная страница должна позволить разработчику быстро выполнить первый успешный запрос.
- Ошибки — часть интерфейса. Не заканчивайте документацию на 200.
- Разделяйте reference и guides. Reference отвечает «что существует?».
