Содержание статьи:
- Что такое API и для чего это нужно
- Для кого документируют API
- Тонкости API-документации
- Инструменты автогенерации API-документации
- Проблемы автогенерации API-документации
- Боремся с недостатками
- Создание API документации в Документерре
API – это устойчивый тренд. Чтобы убедиться в этом, достаточно ознакомиться с последним отчетом Postman, одной из самых известных и мощных платформ для работы с API. На протяжении уже пяти лет специалисты Postman изучают рынок API, проводят исследования и отмечают тенденции индустрии.
Для своего последнего отчета они опросили более 40 тысяч человек, так или иначе связанных с API: разработчиков, тестировщиков, технических писателей и многих других. И, судя по полученным ответам, сегодня активное использование API в бизнесе – это залог конкурентоспособности. Все больше платформ строятся на базе API, все выше спрос на использование микросервисов, на масштабируемость и гибкость процессов. Цифры подкрепляют уверенность в том, что API – это не кратковременный тренд: более 92% опрошенных отмечают, что количество инвестиций в API в ближайшие 12 месяцев останется неизменным или даже увеличится.
Соответственно, экосистема вокруг API тоже активно растет, разрабатываются новые стандарты и инструменты, устанавливается определенная культура. Например, GitHub является крупнейшим веб-сервисом для хостинга IT-проектов и их совместной разработки. Документация по API – неотъемлемая часть этой экосистемы, и у технических писателей возникает множество вопросов по поводу этого типа документов:
- Как ее писать? В чем? Должна ли она ограничиться автогенерацией? Использовать ли заголовки?
- Где публиковать API-документацию, чтобы разработчикам было удобно ей пользоваться, а писателям – вносить изменения?
- Что делать, если пользователю нужны и формальная API-документация, и примеры использования, информация по внедрению и так далее?
В этой статье мы ответим на все эти вопросы, описываем что такое API и расскажем, чем вам может помочь Документерра.
Что такое API и для чего это нужно?
API (Application Programming Interface, интерфейс программирования приложений) означает описание готовых классов, функций, методов и запросов для взаимодействия программ и приложений друг с другом. Проще говоря, то, что позволяет различным сервисам обмениваться информацией. Иногда для того, чтобы объяснить принцип работы API, используют концепцию «черного ящика», который принимает запросы и выдает результаты. Концепция подразумевает, что стороннему разработчику не нужно знать, как именно реализованы внутренние процессы в том или ином API, достаточно знаний о том, как с ним правильно взаимодействовать через внешний интерфейс.
Результаты взаимодействия сервисов мы наблюдаем и используем ежедневно:
- ваше любимое приложение для просмотра прогноза погоды через API получает данные от сервиса, который их собирает;
- приложение-гид по вашему городу отмечает различные точки интереса – от достопримечательностей до ресторанов или пробок на дорогах – через API других сервисов;
- быстрая регистрация в приложениях через аккаунты в социальных сетях также выполняется с помощью специального API-протокола;
- онлайн-маркетплейсы через API дают продавцам возможность управлять магазинами;
- любая онлайн-оплата тоже всегда проходит через специальный API-сервис.
И это далеко не полный список ситуаций, в которых разработчики приложений и сервисов используют API для облегчения процесса разработки и улучшения пользовательского опыта в конечном итоге. Среднее количество API-запросов, которые ваш смартфон выполняет в минуту на ежедневной основе, может исчисляться сотнями.
Но для того, чтобы интеграция API в проект проходила гладко, чтобы функционал API использовался полноценно и всесторонне, необходима качественно написанная документация, которая содержит в себе всю информацию по работе с API: описание методов и классов, параметры запросов и ответов, примеры вызовов, информацию об авторизации и аутентификации и многое другое.
Для кого документируют API?
В отличие от большинства пользовательских справок, ориентированных на конечного пользователя продукта, API-документация обычно создается для внутреннего использования с фокусом на потребностях разработчиков, потому что API чаще всего применяется для взаимодействия между разными компонентами или сервисами внутри одного программного комплекса. В качестве примера можно рассмотреть микросервисную архитектуру, когда в одном приложении задействуется ряд микросервисов – для авторизации пользователей, для доступа к базе данных, для интеграции с другими сервисами и так далее. Взаимодействие происходит через API, каждое из которых может быть разработано отдельной командой. И чтобы разработчики приложения могли использовать эти API корректно, требуется внутренняя API-документация.
Тем не менее, иногда бизнес предоставляет доступ к API внешним разработчикам. Например, CRM-системы с возможностью интеграции в сервисы клиентов, платежные сервисы с интеграцией в сайт покупки товаров, система контроля доступа в здание, интегрированная с системой распознавания лиц на входе. И здесь тоже не обойтись без качественной документации возможностей и особенностей конкретного API.
Тонкости API-документации
У API как объекта документирования есть ряд особенностей, отличающих его от других. В первую очередь, API-документация довольно формализована, так как создается по определенным шаблонам и стандартам, и состоит из следующих пунктов:
- общее описание возможностей API, чтобы можно было сразу понять, для решения каких задач и каким образом он предназначен;
- инструкции по началу работы – регистрация, получение ключей доступа, строка запроса и так далее;
- примеры запросов по разным сценариям использования API, чтобы принципы работы были четко визуализированы;
- информация об ограничениях – количество запросов в единицу времени, объем передаваемых данных;
- описание возможных ошибок с пояснением их причин и способов решения;
- инструкции по интеграции API;
- описание отличий между версиями API;
- контакты службы поддержки.
Информация в API-документации традиционно подается максимально подробно и детально, акцент делается на точности формулировок и однозначности прочтения. Еще одна характерная черта – большое количество фрагментов кода и примеров, а также частое повторение информации, например, в описании схожих конечных точек или эндпоинтов (от англ. endpoint), параметров запроса/ответа и так далее.
Исходя из вышесказанного, современный подход к документированию API часто предполагает автоматическую генерацию документа на основе формального описания в специализированных форматах вроде OpenAPI, Swagger, SOAP. То есть, API-документация часто пишется не на основе текстовых описаний и интервью с разработчиками, а по структурированным спецификациям самих интерфейсов взаимодействия. В чем-то это похоже на процесс автогенерации документации по исходному коду при помощи инструментов вроде NDoc. Это, разумеется, упрощает процесс документирования и удобно тем, что не требует ручного труда: при любых изменениях в API можно просто заново сгенерировать актуальную версию документации.
Но что делать, если формального описания нет? Такое тоже случается, и тогда документация пишется вручную как набор текстовых описаний и примеров.
Мы считаем, что лучше всего сочетать оба способа. То есть, начать с того, что генерировать базовую документацию из формальных спецификаций и дополнять ее примерами использования, рекомендациями и другой информацией вручную. Таким образом API-документация будет более полноценной, всесторонней и полезной.
Инструменты автогенерации API-документации
Один из самых распространенных современных подходов к написанию API-документации – автоматическая генерация документа на основе формального описания в специализированных форматах вроде OpenAPI, Swagger, SOAP.
Для автогенерации существуют определенные инструменты:
- Swagger UI – пожалуй, самый распространенный. Генерирует интерактивную документацию из описания OpenAPI. Позволяет тестировать API прямо в браузере.
- ReadMe – генератор документации из описания OpenAPI со множеством возможностей визуализации и кастомизации.
- Stoplight – еще один инструмент для автоматической генерации документации с возможностью визуального проектирования API в веб-интерфейсе.
- Postman – популярное приложение для тестирования API, также умеет создавать базовую документацию на основе коллекции запросов.
- Redoc – генератор документации, фокусируется на простоте интеграции и высокой производительности.
Проблемы автогенерации API-документации
Какой бы удобной и простой ни казалась возможность сгенерировать документацию автоматически, нельзя не указать несколько серьезных ограничений.
Первый – описания методов и параметров могут быть непонятны внешнему пользователю, так как изначально они пишутся разработчикам на языке, понятном в первую очередь другим программистам. Чтобы сделать документацию доступной внешним пользователям API, нужна помощь технического писателя, его активное участие в процессе совместно с разработчиками – и возможность изменять исходный файл описания (OpenAPI и др.), чтобы перефразировать формулировки разработчиков и добавить примеры и пояснения там, где это необходимо конечному потребителю API. Задачи писателя могут заключаться в ревью файла определения после того, как разработчики внесут в него изменения, или в создании текстовой части описания как таковой.
Второе ограничение автогенерируемой документации API – ее обособленность от остального контента. Автоматические генераторы вроде Swagger UI создают отдельную HTML-страницу с динамически формируемым контентом. Это удобно для быстрого просмотра и тестирования API, но результат получается изолированным от общей структуры сайта, например. А это может привести к сложностям с индексацией и поиском по такой документации. Внешние поисковые системы просто не увидят содержимое. Проблема решается интеграцией API-документации со статическими страницами сайта, например, в виде отдельного раздела справочника.
И третий серьезный недостаток – формальная структура автосгенерированной документации может быть неудобна для работы технического писателя. Нередко она представляет собой набор разделов по каждому методу API с описанием параметров и примерами вызова, но иногда возникает необходимость описать более высокоуровневые сценарии использования API, не привязанные к какому-то одному методу. А автогенерация обычно не предполагает специальных разделов в структуре документа, предназначенных для ручного заполнения.
Боремся с недостатками
Как же можно упростить создание API-документации и при этом решить указанные выше проблемы? Наш опыт позволил выработать несколько решений.
Во-первых, технических писателей необходимо включать в процесс еще на этапе разработки API-определения.
Во-вторых, важно интегрировать API-документацию с другими информационными ресурсами – базами знаний, справочниками, руководствами. То есть, организовать централизованное хранилище информации в пределах одной платформы.
В-третьих, необходимо обеспечить возможность техническим писателям расширять опубликованную API-документацию разделами с дополнительными примерами, написанными вручную.
И если реализация первого решения зависит только от вашей команды, то со вторым и третьим может помочь Документерра – современная и удобная облачная платформа. Одно из ее ключевых преимуществ – возможность создавать документацию разного рода: публичные справки пользователя, внутренние базы знаний, документацию для программного обеспечения, мануалы и инструкции, а также API документацию. Единое централизованное хранилище позволит вам содержать всю необходимую информацию в порядке и работать с ней максимально оперативно. Более того, с Документеррой вы получаете полноценный информационный портал с мощным поиском и контролем доступа. В рамках этого портала вам достаточно просто создать несколько проектов, каждый – для отдельного вида документации от внутренней базы знаний до партнерской, и настроить права доступа. За счет простого и интуитивно понятного стильного интерфейса сделать это будет очень легко.
Если же говорить строго об API-документации, то отметим, что в Документерре вы можете как автогенерировать документацию с возможностью поиска по контенту, импортируя файл OpenAPI, так и создавать API-документацию вручную в случаях, когда OpenAPI не используется. При импорте определений вы можете как загрузить файл, так и указать его URL-адрес: система запомнит этот адрес, и в дальнейшем обновлять автосгенерированные документы можно будет одним нажатием кнопки
Также отметим, что в рамках одного проекта можно импортировать несколько API-определений (каждое будет представлено отдельным разделом в дереве содержания), а потом дополнить их документацией, созданной вручную, чтобы дать более комплексные примеры использования, вводные пояснения и так далее.
* * *
Документация API играет ключевую роль в разработке современного программного обеспечения, позволяя программистам проще и эффективнее использовать API для взаимодействия различных приложений и сервисов. Чаще всего API документируется для нужд внутренних разработчиков, хотя иногда требуется и внешняя документация. Комплексный подход к документированию API – то есть, сочетающий автогенерацию и создание контента от руки – один из лучших способов сделать API-документацию максимально информативной и удобной для всех. А хорошо организованная документация значительно упростит процесс разработки API-ориентированных решений. Документерра – платформа для публикации API-документации, а если вы не используете OpenAPI, то и для разработки. И, определенно, отличный первый шаг к централизации хранения всей технической документации. Запишитесь на интерактивное демо, чтобы узнать подробности.
