Схема отвечает на определённый класс вопросов
OpenAPI отлично описывает операции, параметры, структуры запросов и ответов, статус-коды и повторно используемые схемы. Поэтому спецификация удобна как источник для генерируемого reference и автоматической проверки.
Проблемы начинаются, когда команда считает, что полная схема автоматически создаёт полную документацию для разработчика.
Разработчику нужен путь
Новый пользователь API сначала спрашивает не о каждом поле. Ему нужно понять, как аутентифицироваться, какую среду использовать, какой минимальный запрос успешен, как связаны ресурсы, где возможна eventual consistency и как устроены повторы.
Ответы на такие вопросы должны находиться в концептуальных и процедурных материалах, связанных со справочником.
Примеры передают семантику
Схема может сообщить, что поле принимает строку. Хороший пример показывает реалистичное значение, связь полей и обычный ответ сервера. Примеры стоит проверять автоматически, где это возможно, и использовать для демонстрации решений, а не только для удовлетворения валидатора.
Держите примеры достаточно близко к контракту API, чтобы изменение становилось заметным на ревью.
Ошибка — такой же полноценный сценарий
Сгенерированный reference часто перечисляет ошибки, но не учит восстановлению. Объясняйте, какие ошибки можно повторять, какие означают недопустимое состояние, как сообщается rate limit и какие идентификаторы нужны поддержке.
Не придумывайте гарантии, которых нет в реализации. Неясное поведение retry или idempotency — продуктовый вопрос, а не пробел, который автор должен заполнить красивой прозой.
Пусть OpenAPI делает то, что умеет лучше всего
Используйте спецификацию, чтобы не дублировать факты уровня полей, генерировать таблицы, проверять примеры и структуру. Человеческое редакционное усилие тратьте на ментальные модели, сценарии, компромиссы и восстановление.
Хорошая API-документация относится к схеме как к доказательству, а к опубликованному сайту — как к опыту разработчика, построенному вокруг этого доказательства.
Практический разбор
Превратите «OpenAPI — источник истины, но не вся API-документация» в одну законченную задачу разработчика. Возьмите вымышленный, но реалистичный ресурс — например отчёт, устройство или заказ — и опишите кратчайший путь от аутентификации до успешного результата. Включите запрос, важные поля ответа, одну вероятную ошибку и следующее действие после неё. Пример должен быть принципиально выполнимым даже без живого сервиса.
Проверьте его так, будто по нему действительно пишут клиент:
- какие значения разработчик обязан заменить;
- какие идентификаторы возвращает сервер и где они используются дальше;
- какой статус или поле подтверждает успех;
- что делать при ошибке credentials, входных данных или rate limit.
Если ответы разбросаны по несвязанным страницам, документация может быть формально полной, но практически слабой. Хорошая API-документация позволяет предсказать взаимодействие с системой, а не только узнать названия endpoint-ов.
Короткий редакционный чек-лист
- Схема отвечает на определённый класс вопросов. OpenAPI отлично описывает операции, параметры, структуры запросов и ответов, статус-коды и повторно используемые схемы.
- Разработчику нужен путь. Новый пользователь API сначала спрашивает не о каждом поле.
- Примеры передают семантику. Схема может сообщить, что поле принимает строку.
- Ошибка — такой же полноценный сценарий. Сгенерированный reference часто перечисляет ошибки, но не учит восстановлению.
