API reference (справочник API) — это тип технической документации, который систематически описывает элементы программного интерфейса — классы, методы, функции, параметры, типы данных, коды ошибок — и предназначен для разработчиков, использующих этот API в своих проектах.
В отличие от концептуальной или обучающей документации (руководств, туториалов), справочник API не объясняет, зачем и как решать конкретную задачу, а описывает саму структуру интерфейса: что принимает и возвращает каждый метод, какие есть обязательные и необязательные параметры, какие исключения или ошибки возможны.
Основные особенности справочника API
Систематическое описание интерфейса
Каждый элемент API (класс, метод, свойство, событие) документируется по единому шаблону — назначение, параметры, возвращаемое значение, примеры.
Разделение по платформам и фреймворкам
Крупные экосистемы могут включать несколько параллельных справочников API — например, отдельно для разных SDK, фреймворков или языков программирования, которые используются для одних и тех же задач.
Формальная, а не повествовательная структура
Информация организована по строгой иерархии (пространство имён → класс → метод → параметр), а не в виде связного текста.
Частая генерация из кода
Значительная часть справочника API может создаваться автоматически из комментариев в исходном коде (docstring, XML-документация и подобное), а не писаться вручную полностью.
Как создаётся справочник API
Справочник API формируется по следующим принципам:
- определяется структура описания для каждого элемента интерфейса (класс, метод, параметр, тип возвращаемого значения);
- контент может генерироваться автоматически из аннотаций в коде или дополняться вручную техническим писателем;
- элементы группируются по модулям, пространствам имён или функциональным областям;
- добавляются примеры кода, иллюстрирующие типовое использование каждого элемента.
Где используется справочник API
Справочник API применяется:
- в документации SDK, библиотек, фреймворков и платформ для разработчиков;
- при описании нескольких параллельных реализаций одного и того же API для разных языков или платформ (например, отдельные справочники для C#, Win32 и WinRT в рамках одной экосистемы);
- как часть портала для разработчиков (developer portal) наряду с руководствами и туториалами;
- при документировании внутренних API компании для внутренних команд разработки.
Для чего нужен справочник API
Справочник API помогает:
- быстро находить точное описание конкретного метода, класса или параметра;
- снижать количество ошибок интеграции за счёт точного описания входных и выходных данных;
- давать разработчикам единый источник истины о возможностях и ограничениях интерфейса;
- поддерживать актуальность технической информации по мере развития API.
Преимущества хорошо организованного справочника API
- быстрый поиск нужной информации без чтения всей документации целиком;
- снижение числа ошибок интеграции благодаря точности описаний параметров и типов;
- согласованность документации с фактическим состоянием кода при автогенерации;
- удобство работы для разработчиков разного уровня опыта — от новичков до экспертов.