Справочники, OpenAPI, примеры, путь разработчика и контракты интерфейсов.
Технически валидный запрос ещё не хороший пример. Выбирайте примеры, которые раскрывают модель API, используют реалистичные значения и помогают разработчику предсказать следующий шаг. Пример, автоматически собранный из схемы, может быть синтаксически правильным и при этом ничему не учить.
Хорошая документация по аутентификации описывает весь жизненный цикл учётных данных: получение доступа, передачу, ротацию и диагностику ошибок. До первого HTTP-запроса объясните prerequisites, роли, окружения и способ выдачи учётных данных.
Справочник ошибок полезен только тогда, когда помогает определить условие, понять ответ и выбрать безопасное следующее действие. Описывайте условие возникновения ошибки, а не только код и сообщение.
Хорошая API-документация сочетает машиночитаемый контракт, человеческие объяснения, запускаемые примеры и явное описание ошибок. У REST API-документации сразу две аудитории: машины и люди.
Описание OpenAPI позволяет генерировать точную структуру справочника, но разработчику всё равно нужны концепции, сценарии, аутентификация, примеры и восстановление после ошибок — то, чего одна схема объяснить не может. OpenAPI отлично описывает операции, параметры, структуры запросов и ответов, статус-коды и повторно используемые схемы.