Api документация что это

Что такое API документация и как ее правильно составить и использовать?

В современном мире API повсюду. Эта аббревиатура встречается во всех сферах, которые имеют дело с мобильными приложениями. Это касается самого разнообразного софта – интернет-магазинов, финансовых компонентов, сервисов приема и обработки платежей и т.д. Любой сервис, который подразумевает использование API, нуждается в соответствующей документации.

Именно на этом этапе многие компании сталкиваются с проблемами из-за того, что документы часто бывают неконкретными и неточными. В этом материале вы узнаете, что такое АПИ документация, почему ее качество во многом влияет на успех вашего продукта в целом, и какие особенности существуют.

Что такое API-документация? Где она необходима?

Сначала необходимо разобраться в том, что такое API. API (Application Programming Interface) – это способ интеграции приложений. Это совокупность функций и процедур, при которых различные программы могут взаимодействовать между собой. API применяются в самых различных сферах, например:

• Приложения платежных систем.
• Эквайринг.
• P2P-сервисы.
• Безопасность и другие сферы.

Для того чтобы АПИ работало эффективно, существует специальная документация, в которой детально описаны все технические процессы и способы их применения. Чем подробнее документация, тем соответственно быстрее и качественнее будет проходить проходить интеграция готового продукта.

Почему важна качественная API-документация?

Интеграция готового программного продукта – это довольно сложный и ответственный процесс, ведь во многом от этого зависит весь дальнейший успех. Программные компоненты обеспечивают отправку данных в ручном или автоматическом режиме. Скорость передачи этих данных и их корректность очень важны для дальнейшего успеха всего программного продукта.

АПИ обеспечивает проверку интеграции одной системы в другую. Например, клиент интернет-магазина может заметить это на примере реализации платежных инструментов на платформах. Для интеграции платежных инструментов необходима API-документация, ведь в противном случае данные просто не будут доходить из интернет-магазина в платежную систему.

Такая документация в контексте платежных провайдеров и банков-эквайеров выполняет очень важную роль в рамках взаимодействия нескольких не связанных между собой систем. Фактически, описание АПИ содержит доступные эндпоинты, их детальное описание, схемы работы, примеры запросов и ответов, структуры коллбэков, а также списки обязательных параметров для тех или иных запросов. Что это значит простыми словами? Это значит, что без использования API-документации две системы не смогут корректно взаимодействовать друг с другом, так как весь механизм интеграции и взаимодействия должен быть детально описан, с учетом “corner-кейсов”.

Также качественная API-документация важна и с точки зрения статистики. Сервисы могут собирать разнообразные статистические данные, которые важны для анализа рынка, составления портрета клиента, мониторинга эффективности работы платформы и т.д.

Что должна включать в себя API документация?

Существует ряд важных требований для API-документации. Первое и главное из них – читаемость. Документация фактически должна представлять собой краткую справку, из которой разработчик должен узнать, какие есть возможности, зачем и как их использовать. Чем более читаема документация, тем меньше вопросов к службе поддержки.

Структура API-документации может отличаться, однако существует 5 стандартных блоков. Они следующие.

• Аутентификация. Этот блок обеспечивает безопасность запросов. Система должна знать, как определить, кто именно подает запрос и как на него стоит реагировать. Это реализуемо при помощи своеобразных ключей взаимодействия и эндпоинтов для аутентификации запросов.
• Объект. В данном случае предоставляются данные клиента. Например, это могут быть имя, адрес электронной почты, номер телефона или любая другая важная информация. Документация должна содержать список обязательных параметров в зависимости от вида и типа запроса и используемого эндпоинта. Если в технической спецификации АПИ не указаны обязательные параметры для передачи в рамках запроса, такая документация не может считаться качественной и применимой.
• Запрос. Для подачи запросов используются HTTP-методы (создание, чтение, обновление, удаление), заголовки и полезная нагрузка запроса – непосредственно информация, с целью передачи которой он осуществляется. Важно понимание типа запроса – например, GET или POST в зависимости от того, какой процесс необходимо выполнить в рамках бизнес-задачи.
• Ответ. На любой запрос должен поступить ответ. Он включает в себя код статуса и полезную нагрузку – информацию, которую сервер передает клиенту в ответ на запрос. Стандартно, любая качественная API-документация должна содержать примеры запроса и ответа, с разными вариантами ответа от сервера (например, коды ответа 200 (ОК) и 500 (Internal Server Error)), чтобы у разработчика, занимающегося интеграцией, возникало как можно меньше вопросов, а на построение и отправку запросов, а также дебаг по части ответов – уходили считанные минуты.
• Тестовое окружение. Любой качественный продукт содержит раздел с тестированием, где описаны методологии и инструменты, необходимые для воспроизведения его работы перед непосредственным запуском. Если мы говорим о платежном провайдере, в разделе с тестированием должна содержаться информация о тестовых банках и картах, которые могут быть использованы с эмулятором (без реального списания средств, но с эмуляцией успешного/неуспешного проведения платежа).

Все эти блоки представляют собой определенный шаблон. Именно по нему следует ориентироваться при подготовке документации. И очень важно при этом сохранить ее читаемость. API должна оставаться понятной для разработчика. Не перегружайте ее лишней информацией.

Почему API должна быть актуальной?

Для продуктов, которые активно развиваются, очень важно поддерживать API в актуальном состоянии. Это связано с тем, что информация в документации достаточно быстро устаревает. Например, это может произойти из-за изменения кода. Если это произошло, то API-документация больше не актуальна. Ее необходимо обновлять.

С проблемой неактуальной документации часто сталкиваются разработчики. Из-за этих проблем приходится обращаться в службу технической поддержки. В результате техподдержка получает десятки или даже сотни одинаковых запросов из-за того, что разработчики сталкиваются с одной и той же ошибкой, возникшей по причине отсутствия актуализации документации.

Компания PayAdmit провела полное обновление API-документации для клиентов, использующих наши программные компоненты. Вся информация полностью актуальна, и у вас не возникнет проблем. В любом случае, специалисты нашей службы поддержки всегда на связи и готовы предоставить ответы максимально быстро и помочь с интеграцией наших платежных продуктов.

Документация API: руководство для технических писателей

На этом курсе по разработке документации API не будем вести речь об абстрактных понятиях, лучше подойдем практически к документированию API: изучим документацию API на примере использования различных API сервисов прогнозов погоды.

Используя API на этом курсе, мы узнаем что такое “конечная точка” или эндпоинт, какие у нее могут быть параметры, типы данных, что такое аутентификации, curl, JSON, поближе познакомимся с командной строкой, консолью разработчика Chrome, JavaScript и многими другими деталями, связанных с REST API.

Идея курса: посмотреть на реальные сценарии использования API, сделав этот курс эффективным. Изучать концепты API независимо от контекста мы не будем.

На курсе мы изучим стандарты, инструменты и спецификации REST API. Узнаем о необходимых разделах в документации API, проанализируем примеры документации REST API от различных компаний, узнаем, как присоединиться к проекту с открытым исходным кодом, для получения опыта, и многое другое.

О REST API

Вкратце, REST API (которые является разновидностью веб-API) используют запросы и ответы, что мало чем отличается от посещения веб-страницы. Вы делаете запрос к ресурсу, хранящемуся на сервере, и сервер отвечает запрошенной информацией. Протокол, используемый для передачи данных — HTTP. «REST» (Representational State Transfer) означает репрезентативную передачу состояния.

Более подробно о принципах REST в разделе Что такое REST API?. В документации API описываются различные конечные точки, их методы, параметры и другие сведения, а также документируются образцы ответов от конечных точек.

От практики до документации

После изучения модуля “Используем API как разработчики”, откроются новые горизонты и простой технический писатель станет техническим писателем, которому может документировать конечные точки API.

Как технические писатели, будем рассматривать каждый элемент в документации API:

1. Описание ресурса
2. Конечная точка и методы
3. Параметры
4. Пример запроса
5. Пример ответа

Изучение этих разделов даст четкое представление о том, как документировать API. Также узнаем, как документировать концептуальные разделы API, такие как руководство по началу работы, коды статусов и ошибок, авторизация запроса и т.д.

Наконец, изучим разные способы публикации API документации, изучим инструменты и спецификации, такие как GitHub, Jekyll и подход Docs-as-code. Узнаем, как использовать шаблоны, создавать интерактивные консоли API, чтобы пользователи могли сделать запросы и посмотреть ответы, а также узнаем, как управлять своим контентом с помощью контроля версий.

Мы также окунемся в спецификации, такие как спецификация OpenAPI и Swagger, который предоставляют инструментарий для спецификации OpenAPI. Кроме того, узнаем, как документировать нативные библиотеки API и генерировать Javadoc. Вместе с концепциями будут продемонстрированы реальные примеры.

Для кого этот курс

Курс в первую очередь нужен следующим специалистам:

• Профессиональные технические писатели, желающие перейти от документации GUI к документации, ориентированной на API для разработчиков;
• Студенты изучающие область технических коммуникаций, которая все больше фокусируется на документации для разработчиков;
• Разработчики, которые документируют свои собственные API-интерфейсы и хотят узнать лучшие практики по структуре, терминологии и стилю с помощью технических документов.

Организация курса

1. Введение в REST API
   • API-интерфейсы REST очень популярны в мире IT, и веб превращается в совокупность взаимосвязанных API-интерфейсов. REST API состоят из запросов и ответов от сервера. Технические писатели способные писать документацию для разработчиков имеют огромные перспективы. Этот курс поможет разобраться с документированием API, особенно при помощи практических занятий.
2. Используем REST API как разработчики
   • Роль разработчика поможет лучше понять потребности разработчиков, а также то, что разработчики обычно ищут в документации API. Разработчики часто используют такие инструменты, как Postman или curl, для совершения запросов. Они смотрят на структуру ответа и динамически интегрируют необходимую информацию в веб-страницы и другие приложения.
3. Документирование конечных точек API
   • Документация конечных точек API состоит из пяти основных разделов: описания ресурсов, конечные точки и методы, параметры, примеры запросов, примеры ответов и схемы. Чтобы задокументировать конечные точки API, старайтесь предоставлять подробную информацию для каждого из этих разделов.
4. Спецификация OpenAPI и Swagger
   • Спецификация OpenAPI предоставляет один из способов описания REST API и включает все разделы, упомянутые в модуле Документирование конечных точек API. Фреймворки, такие как Swagger UI, могут анализировать спецификацию OpenAPI и генерировать интерактивную документацию, которая позволяет пользователям опробовать конечные точки при изучении API.
5. Тестирование документации API
   • Тестирование документации имеет решающее значение для предоставления точной, полной информации. Из-за высокого уровня сложности и технических требований документации API и иной документации разработчиков многие технические писатели склонны брать информацию из такой документации и добавлять ее без личного тестирования. Однако простая игра в редакционную/издательскую функцию может сделать из вас простого секретаря.
6. Концептуальные разделы API
   • В то время как адресные темы в API, как правило, получают наибольшее внимание, концептуальные разделы, такие как разделы о начале работы, информация об авторизации, возможных лимитах скорости, кодах состояния и ошибок, кратких справочных руководствах и других темах, составляют около половины документации. Этими вопросами обычно занимаются технические писатели, а не разработчики. Вы можете оценить качество документации API, посмотрев, включает ли она эти не справочные темы.
7. Публикация документации API
   • Документация по API часто соответствует принципу docs-as-code, где инструменты для создания и публикации документации тесно связаны с теми же инструментами, которые разработчики используют для написания, управления, построения и развертывания кода. Docs-as-code включает в себя использование облегченных форматов разметки, таких как Markdown, совместную работу с помощью Git или других систем управления версиями, создание сайта документации с помощью генератора статического сайта и развертывание его с помощью модели непрерывной сборки, где сборка происходит на сервере при фиксировании изменений в определенной ветви.
8. Работа технического писателя API
   • Чтобы получить работу, имеющую отношение к документации API, нужно продемонстрировать портфолио и технические способности. В портфолио должны быть включены образцы документации, написанной для разработчиков. Одним из способов создания такого портфолио является работа над проектом с открытым исходным кодом. Постоянное развитие мира документации для разработчиков потребует постоянного изучения больших объемов кода, несмотря на свою сложность.
9. Нативные библиотеки API
   • API нативных библиотек относятся к Java, C ++ или другим API, специфичным для программирования. При таком подходе вместо запроса информации через Интернет, библиотека кода загружается и интегрируется в проект. Библиотека компилируется непосредственно в сборку приложения (а не доступна через веб-протоколы, как с REST API). Хотя такой тип API встречается реже, он включен здесь частично, для пояснения, что отличает API REST от API нативных библиотек.
10. Глоссарий и источники
    • Документация API полна жаргонов, сокращений и множества новых терминов. Этот глоссарий предоставляет список терминов и определений. Кроме того, этот модуль содержит дополнительные упражнения и информацию, например, дополнительные действия по вызову API или дополнительную информацию об альтернативных спецификациях.

Последовательность и действия

Необязательно изучать модули по порядку — можно “гулять” по ним по своему усмотрению. Но некоторые из модулей (например, Используем REST API в роли разработчика и Конечные точки API) желательно пройти последовательно.

Кроме основной цели курса — помочь в обучении, существует множество видов деятельности, которые требуют практического программирования и других упражнений. Наряду с учебной деятельностью существуют также концептуальные глубокие погружения, но основное внимание всегда уделяется обучению на практике.

Практические занятия помечаются иконкой в заголовке раздела: ��‍��

Упражнения интегрированы в модули, но можно увидеть список заданий в «Практических занятиях».

Курс назван «курсом», а не книгой или веб-сайтом, главным образом потому, что в каждом модуле включены практические занятия для наработки опыта.

Поможет ли курс получить работу техписателя API?

Самая распространенная причина, по которой люди проходят этот курс — непонимание процесса документирования API. Курс поможет осуществить задуманное, но только пассивное чтение разделов не поспособствует этому. Необходимо выполнять упражнения, в каждом модуле, особенно те, которые связаны с работой над контентом из опен-сорс проекта. Такие практики имеют решающее значение для накопления опыта и пополнения портфолио. Более подробные сведения приведены в модуле Работа технического писателя API.

Навыки программирования не требуются

Что касается необходимого технического бэкграунда для прохождения курса, какие-либо знания специфических языков программирования не нужны, но зная базу HTML, CSS и JavaScript будет немного легче.

Этот курс рассчитан для новичков. Если есть понимание концепции программирования, можно пропускать некоторые разделы и переходить к темам, которые хотите узнать больше.

Некоторые примеры кода в этом курсе используют JavaScript. JavaScript может быть языком, который фактически используется при документировании REST API, но могут быть и другие языки или платформы программирования, которые тоже важно знать.

JavaScript — один из самых полезных и простых языков для изучения, поэтому его проще использовать в примерах кода для данного введения в документацию по REST API. JavaScript позволит тестировать код, просто открывая его в браузере (а не компилируя в IDE). (Быстрый ускоренный курс по JavaScript).

Инструменты для работы

• Текстовый редактор (Atom или Sublime text);
• браузер Chrome с его встроенной консолью Javascript, которая хорошо подходит для проверки JSON. Firefox тоже подойдет;
• Postman — приложение, которое позволяет вам делать запросы и видеть ответы через GUI-клиент;
• curl необходим для выполнения запросов к конечным точкам из командной строки. На компьютерах Mac уже установлен curl. Пользователи Windows должны следовать инструкциям по установке curl здесь. (Примечание: выбирайте одну из «бесплатных» версий для установки curl.);
• Git — инструмент контроля версий, который разработчики часто используют для совместной работы над кодом. Для Windows здесь описана установка и настройки Git и эмулятора терминала Git BASH. Для Mac смотрите Загрузка Git, можно рассмотреть возможность установки iTerm2;
• аккаунт на GitHub будет использоваться для различных действий, иногда для демонстрации рабочего процесса Git, а иногда в качестве службы аутентификации для инструментов разработчика. Если еще нет учетной записи GitHub, самое время ее создать;
• аккаунт StopLight, сервиса, который предоставляет инструменты визуального моделирования для работы со спецификацией OpenAPI. Создать учетную запись Stoplight можно, используя свои учетные данные GitHub;
• ключ к API OpenWeatherMap. Мы будем использовать API OpenWeatherMap для некоторых упражнений. Для активации ключа API OpenWeatherMap требуется несколько часов, поэтому лучше получить ключ API заранее — тогда, когда вы приступите к действиям API OpenWeatherMap, все будет готово. Чтобы получить свой (бесплатный) ключ API OpenWeatherMap, перейдите по адресу https://openweathermap.org/. Нажмите Зарегистрироваться в верхней панели навигации и создайте учетную запись. После того, как вы зарегистрируетесь, войдите в систему и найдите ключ API по умолчанию на панели инструментов разработчика. Он находится на вкладке API Keys. Скопируйте ключ в то место, где его легко найти.

Видео записи

Видео записи курса здесь.

Подборка предстоящих презентаций в блоге автора курса для получения подробной информации о будущих семинарах и презентациях.

Презентации курса

Есть различные презентации, охватывающие различные модули этого курса, которые можно использовать при подготовке и проведения семинаров. Преподаватель, адаптирующий этот материал для курса по документации API в программе технической коммуникации, может клонировать и изменять слайды. Слайды курса здесь.

Слайды используют RevealJS, который представляет собой HTML / CSS / JS-фреймворк для слайдов.

Актуальность контента курса

Одной из проблем любого технического курса является обеспечение актуальности контента. Технологии быстро меняются, и благодаря многим практическим занятиям в этом курсе, некоторые шаги легко устаревают с течением времени. Автор курса пытается сохранить здоровый баланс между общими и конкретными деталями в содержании курса. Если вы обнаружите, что что-то устарело, или найдены ошибки, pull requests are welcome.

Оставаться в курсе

Если вы проходите этот курс, скорее всего, захотите узнать больше об API. Автор публикует регулярные статьи, в которых рассказывается об API и стратегиях их документирования. Вы можете оставаться в курсе об этих сообщениях, подписавшись на его бесплатную рассылку.

Удачный шаблон документации на API, который будут читать

Представьте, что в рецепте для приготовления еды была бы вводная часть о том, откуда привезли продукты, как их упаковывали и доставляли.

Вы бы стали читать рецепт из 10 страниц, чтобы приготовить салат? Что-то я сомневаюсь. Схожая ситуация бывает в документации, когда она пишется без шаблона по принципу «чем больше, тем лучше».

Если ваши документы не читают, не понимают, или вы не знаете с чего начать описывать интеграцию, то эта статья для вас.

Я тех. лид системных аналитиков и прошла долгий путь к шаблонам документации в разных компаниях.

С чего все начинается

Чаще всего у системного аналитика болит от того, что его техническое задание (ТЗ) не читают. Разрабатывают как поняли, тестируют как услышали, а заказчик ждет вообще другое. Еще болит, а как описать задание разработчику, если в компании нет шаблона?

Самое важное понять, кто и для чего будет пользоваться документацией.

Аналитик думает, что документы нужны всем, а остальные уверены, что им они не нужны. Поэтому для составления удачного шаблона нужно понять, что мотивирует вашу команду прочитать документацию.

Перед нами команда, которая разрабатывает новые интеграции.

Системный аналитик

Отвечает за документацию

Product Owner

Ставит задачи аналитику

Разработчик

Тестировщик

Проверяет, правильно ли сделал разработчик

Задача аналитика — описать интеграцию систем (спроектировать API).

Для чего команде документ

Product owner

В описании ищет ответы на вопросы:

Зачем нужна новая интеграция бизнесу?
Что пользователи получат в результате разработки?

Разработчик

Без документа не понимает как ему делать задачу, поэтому вопросы у него такие:

Что мне делать: параметры запроса-ответа?
В какие системы сходить за данными или передать?

Тестировщик

Прочитав описание интеграции, сможет ответить на вопросы:

Как бы это все сломать: какие ошибки можно сделать?
Где найти тестовые запрос-ответ?
С какими системами есть взаимодействие, чтобы проверить весь путь?

Аналитик другой команды

Этому человеку нужна любая документация, потому что у него один вопрос:

Как переиспользовать или доработать сервис, чтобы ничего не сломать?

Скорость разработки — это важное преимущество, потому что кто первый вышел на рынок с продуктом, тот и выиграл. Время на написание или чтение ТЗ выделяется мало, поэтому документ должен содержать необходимый и достаточный минимум для быстрой разработки.

Из чего состоит шаблон

В шаблоне на интеграцию (API) будут разделы:

Основная информация Запрос/Ответ Входные параметры Проверки Выходные параметры Положительный ответ Ответ с ошибками Описание интеграции Интеграции Интеграция с сервисом №1

Почему именно такая структура?

Спокойствие, только спокойствие, сейчас все расскажу!

Вспомните, у каждого участника команды были вопросы, мотивирующие его прочитать документацию. От них и отталкиваемся, поэтому такое содержание.

Основная информация

В разделе можно найти ответы на вопросы:

Зачем нужна новая интеграция бизнесу?
Что пользователи получат в результате разработки?

Запрос/Ответ, Входные и выходные параметры

В этих разделах документа есть информация:

Что мне делать: параметры запроса-ответа?
Где найти тестовые запрос-ответ?
Как бы это все сломать: какие ошибки можно сделать?

Описание интеграции

Здесь есть ответы на вопросы:

В какие системы сходить за данными или передать?
С какими системами есть взаимодействие, чтобы проверить весь путь?
Как переиспользовать или доработать сервис, чтобы ничего не сломать?

Как применить шаблон на практике

Аналитическая задача — описать интеграцию, которая позволить добавить информацию о животном на сайте. Аналитик понимает, что нужен сервис для работы с данными о животных и метод, который создаст запись (прим. в статье не описано почему именно такой метод спроектирован, потому что статья направлена именно на шаблон описания).

Раздел содержит таблицу, которая позволяет понять, о чем будет документ, и найти все ссылки в одном месте.

Автор — ФИО, кто пишет или правит документ
Задача — ссылка на задачу (например, JIRA) или описание задачи
Бизнес постановка — описание какую пользу приносит эта задача пользователям
Связанные документы — документы или ссылки с описанием, что в них находится

История изменений документа

Раздел содержит таблицу:

Версия — номер версии
Дата — дата в формате ДД.ММ.ГГГ
Автор — ФИО кто создал или изменил документ
Описание изменений — текстовое описание того, что вы добавили в документ.

Запрос/Ответ

Пример запроса и ответа для добавления информации о животном на сайте

Входные параметры

Раздел содержит таблицу:

Параметр — название параметра на английском
Тип данных — указать тип данных параметра с ограничениями по длине если они есть
Обязательность — да/нет
Описание — понятное описание для чего используется параметр
Варианты значений — перечислить варианты значений с пояснениями, для чего они используются или привести пример одного из значений

Проверки

Раздел содержит таблицу:

Параметр — название параметра на английском
Проверка — условие и результат проверки

Выходные параметры

Положительный ответ

Параметры аналогичны входным

Ответ с ошибками

Описание интеграции

Для построения сервиса использовался инструмент plantuml. Работа с ним описана в статье https://habr.com/ru/post/661931/

Посмотреть реализованный сервис можно по ссылке https://petstore.swagger.io/#/pet/addPet. Для удобства описания были придуманы некоторые проверки и коды ошибок 🙂

Интеграции

В разделе описываются сервисы, которые вызываются из выше описанного метода. Формат описания также будет содержать запрос и ответ, входные и выходные параметры.

Например, если бы метод POST /pet пошел бы в следующую систему для сохранения информации о животном.

Вы получили шаблон технической документации на API . Скачать шаблон google docs можно по ссылке

Его можно адаптировать под потребности людей, которые читают ваши документы. Документ может быть удобен вам, но разработчик, тестировщик и другие ребятам из команды не найдут ответы на свои вопросы. Поэтому хорошей практикой будет систематический сбор обратной связи от вашей команды, а все ли им удобно и понятно в документе.

Возможно вам шаблон не подойдет, но вы всегда можете составить свой и поделиться им в комментариях.

API документация: как документировать API для веб-сервисов?

Многие из нас при выполнении своих обязанностей на работе сталкиваются с необходимостью заглянуть в какой-либо справочник, который даст нам ответ на вопрос. Если вы пользователь ERP / CRM-системы, то при возникших вопросах сразу обращаетесь в ИТ-поддержку. Если вы юрист, то нуждаетесь в соответствующем кодексе, по которому у вас возник вопрос. А если вы занимаетесь разработкой веб-приложений для своего бизнеса или для своих клиентов, то вам будут просто необходимы стандарты разработки и документация для вашего API. В каждой сфере есть своя документация, из которой черпают люди информацию, необходимую им для выполнения своей работы.

Казалось бы, всё так просто. Но в сфере IT (Information technology) всё меняется очень интенсивно. Взаимосвязи программ, приложений и т.п. через API (Application Programming Interface) тоже постоянно меняются. Многие программисты сталкиваются с необходимостью посмотреть стандарты своего языка программирования, API для текущей задачи, способы все это зафиксировать, чтоб было проще и комфортнее работать через документацию в дальнейшем.

Проблема документирования API

API-документация — это техническая документация, в которой фиксируются инструкции о том, как эффективно использовать программное API, аппаратное SCPI или web API.

Для активно развивающихся продуктов поддержка документации API играет немаловажную роль, но при этом стоит не забывать об актуальности этих данных.

Один из вариантов закрытия вопроса с документацией API может быть такой: мы берем отдельного сотрудника (сотрудников) для создания документации по API. Он (они) будут распространять эту документацию в виде файлов или публиковать на сайте. Такой подход вполне рабочий, но имеет ряд существенных недостатков в лице человеческого фактора и быстрого устаревания документации. Человек может что-то забыть, написать неправильно и т.д. Как только код изменился — документация устарела. С неактуальной и ошибочной документацией API-интерфейсов разработчики сталкиваются очень часто. Поиски “правды” в таких случаях увеличивают трудозатраты, что в конечном итоге сказывается на стоимости продуктов.

Так что документация API — это не только фиксирование в документе необходимой информации, но и поддержание её актуальности.

Проблема стандартизации API

Допустим, документирование API было доведено до актуальности, и теперь у нас в доступе всегда безошибочная информация. Но, к сожалению, при наличии актуальной документации трудности не заканчиваются. Получившееся API может быть настолько сложным и неудобным, что работа с ним может стать кошмаром. Ведь в первую очередь работать с ним будут люди, а уже только потом программа. Очевидно, что нужен некий стандарт разработки API, чтобы разработчики даже при беглом ознакомлении понимали, как с ним корректно взаимодействовать. Также наличие стандарта API позволяет использовать средства автоматической кодогенерации, что существенно повышает скорость разработки.

Как решается задача документации API

Прежде чем перейти к решению возникших проблем, необходимо знать существующие протоколы реализации веб-сервисов, как они работают, их особенности. А также познакомиться с различными инструментами для стандартизации API-интерфейсов.

Краткий обзор существующих веб-сервисов API

В веб-разработке активно используются веб-интерфейсы или web API. По мере развития интернет-систем одни web API устаревают, как, например, SOAP (Simple Object Access Protocol), а другие пользуются большим спросом, как, например, REST (Representational state transfer). А также можно встретить и “тёмную лошадку” GraphQL, которую запустил Facebook в 2015 году. Ниже приведены схемы веб-сервисов API.

Рис 1. REST веб сервис

Рис 2. GraphQL веб сервис

Обзор возможных путей решения для REST-архитектуры

Наладить согласованную коммуникацию между всеми видами клиентов и серверным приложением бывает непросто. Отчасти эта проблема решается базовыми положениями REST архитектуры (или любой другой архитектурой, которую вы выберете), тем не менее без описания интерфейса сервера (API) не обойтись. Другими словами, разработчики клиентских приложений должны каким-то образом понимать, как им можно взаимодействовать с серверным приложением, какое это окажет влияние и что они получат в результате.

Один из самых популярных на данный момент способов описания API — это спецификация Swagger. Swagger — это не только спецификация, но еще и целая экосистема для решения разнообразных задач по документированию API.

Список спецификаций для документации RESTful API:

Автогенерация — наше всё

Решением вышеперечисленных трудностей при документировании API может стать генерация автодокументации, т.е. при изменении кода приложения документация автоматически перестраивается с учетом этих изменений. Таким образом, устраняется и человеческий фактор, и проблема неактуальности. Конечно, этот способ требует определенных затрат на начальном этапе. Необходимо настроить систему генерации API-документации, а также разработать и придерживаться набора правил при написании кода.

Кейс TQM Systems: решаем задачу документации REST API

При разработке собственных веб-сервисов и при столкновении с подобными проблемами в документировании API наши разработчики нашли интересное решение, описанное далее. Итак, каким образом мы выполнили документирование REST API?

Почему REST API

При разработке веб-приложений мы используем подход REST для реализации серверной части приложения. Этот подход позволяет легко добавлять новые виды клиентских приложений, которые должны работать с основной бизнес-логикой приложения. Например, на начальном этапе можно ограничиться использованием браузера в качестве платформы для реализации пользовательского интерфейса, а в дальнейшем добавить приложения для смартфонов или настольных компьютеров под управлением различных операционных систем. А так как концепция IoT (Internet of Things или Интернет вещей) набирает обороты, то клиентом нашего приложения может быть не только человек, но и любое устройство. Вероятность того, что придется переписывать все из-за того, что пользователи стали предпочитать одну мобильную платформу другой, значительно уменьшается. Теперь достаточно реализовать клиента для новой платформы. Не надо тратить ресурсы на переработку основного функционала, который уже протестирован и хорошо работает.

Как документировать REST API

При разработке нашего продукта SaaS Solutions мы реализовали RESTful веб-сервис и приложение для работы в браузере с использованием связки технологий .Net Framework + Asp Net Web Api + Angular.js. Для генерации документации воспользовались библиотекой Swashbuckle, которая реализует генерацию документации по спецификации Swagger для .Net-решений.

Пример готовой документации API

В результате получилась вот такая веб-страница с описанием API.

Рис. 3 Пример Рис. 3 Пример документации API, сгенерированный библиотекой Swashbuckle.

Это не просто страница, описывающая API, она также дает возможность протестировать работу API без использования сторонних средств.

Рис 4. Web API Рис. 4 Web API документация с выводом результата работы API

Приведенная выше в качестве примера документация web API демонстрирует, что даже в стадии разработки она уже пригодна для внутреннего использования. Ее наличие значительно упростило взаимодействие между командами, которые разрабатывают серверное и клиентское приложения. После добавления описаний работы методов и форматов возвращаемых значений ее можно будет применять и для внешнего использования.