Валидность — только начало
Пример, автоматически собранный из схемы, может быть синтаксически правильным и при этом ничему не учить. string, 123 и foo проходят множество валидаторов, но скрывают смысл предметной области. Хороший пример даёт контекст: зачем нужен запрос и что успешный ответ позволяет сделать дальше.
Используйте реалистичные идентификаторы и значения, но никогда не реальные секреты и персональные данные.
Постройте небольшой сюжет
Предпочитайте последовательность, похожую на реальную задачу разработчика: создать ресурс, получить его, обновить, обработать ошибку или выполнить очистку. Повторно используйте идентификаторы между шагами, чтобы были видны связи.
На отдельных reference-страницах лучше ссылаться на соответствующий workflow, чем копировать огромный tutorial под каждый endpoint.
Показывайте важный ответ
Не останавливайтесь на запросе. Покажите значимые response headers, статус и тело. Объясните поля, смысл которых неочевиден. Если операция асинхронная, покажите, как клиент узнаёт о её завершении.
Ошибки заслуживают такой же работы. Реалистичный validation error часто объясняет API быстрее ещё одного happy path.
Делайте примеры исполняемыми
Где возможно, запускайте запросы в CI на стабильной тестовой среде или валидируйте payload по схеме. Храните примеры как файлы или генерируемые фрагменты, а не копируйте вручную один и тот же код на несколько страниц.
Если пример нельзя выполнить автоматически, фиксируйте, что именно и когда было проверено.
Оптимизируйте перенос знания
Читатель должен уметь адаптировать пример, а не только вставить его. Объясните одну-две переменные, которые нужно изменить, и условия, которые должны остаться истинными.
Цель примера — полезная ментальная модель. Если после него следующий запрос проектировать не легче, вероятно, это просто декор.
Практический разбор
Превратите «Примеры API должны обучать сценарию, а не украшать reference» в одну законченную задачу разработчика. Возьмите вымышленный, но реалистичный ресурс — например отчёт, устройство или заказ — и опишите кратчайший путь от аутентификации до успешного результата. Включите запрос, важные поля ответа, одну вероятную ошибку и следующее действие после неё. Пример должен быть принципиально выполнимым даже без живого сервиса.
Проверьте его так, будто по нему действительно пишут клиент:
- какие значения разработчик обязан заменить;
- какие идентификаторы возвращает сервер и где они используются дальше;
- какой статус или поле подтверждает успех;
- что делать при ошибке credentials, входных данных или rate limit.
Если ответы разбросаны по несвязанным страницам, документация может быть формально полной, но практически слабой. Хорошая API-документация позволяет предсказать взаимодействие с системой, а не только узнать названия endpoint-ов.
Короткий редакционный чек-лист
- Валидность — только начало. Пример, автоматически собранный из схемы, может быть синтаксически правильным и при этом ничему не учить.
- Постройте небольшой сюжет. Предпочитайте последовательность, похожую на реальную задачу разработчика: создать ресурс, получить его, обновить, обработать ошибку или выполнить очистку.
- Показывайте важный ответ. Не останавливайтесь на запросе.
- Делайте примеры исполняемыми. Где возможно, запускайте запросы в CI на стабильной тестовой среде или валидируйте payload по схеме.
