Что такое документация api спецификации

API документация: как документировать 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Источник

Документирование API

При фразе «Документирование API» многие приходят в ужас, так как, на первый взгляд, это кажется очень трудным, страшным и тяжёлым. Документ по ГОСТу сразу кажется небольшой детской сказкой на этом фоне. Но не так страшен чёрт, как его малюют! Я не говорю, что документирование API — это легко и просто. Да этому нельзя научиться из одной короткой статьи или видео, но если придёт понимание этой темы, то и на изучение этой темы уйдёт гораздо меньше времени. Да–к, что же такое API? И как его задокументировать? В данной статье рассмотрена эта очень непростая тема.

Что такое API?

API (application programming interface) — это набор готовых классов, функций, процедур, структур и констант, предоставляемые самим приложением или операционной системой для взаимодействия с внешними программами.
Например, у вас есть кот Барсик, который любит лежать на обеденном столе. Вам это не нравится. Вы говорите Барсику: «Барсик, брысь со стола!». Барсик хоть и нехотя, но слезает со стола. Так вот, API — это набор команд, благодаря которым кот Барсик понял хозяина, что ему следует слезь со стола. Другой пример, если программу (модуль, библиотеку) рассматривать как чёрный ящик, то API — это множество «ручек», которые доступны пользователю данного ящика и которые он может вертеть и дёргать.
При этом пользователю необязательно понимать и знать, что такое API. API это «язык» общения между двумя программами и необходим программистам. API создаётся чтобы приложения созданные разными разработчикам корректно существовали вместе и могли взаимодействовать друг с другом. Компоненты образуют иерархию, в результате которой высокоуровневые компоненты используют API низкоуровневых компонентов, а те, в свою очередь, используют API ещё более низкоуровневых компонентов. По такому принципу построены протоколы передачи данных по Интернет. Каждый уровень пользуется функциональностью предыдущего («нижележащего») уровня и, в свою очередь, предоставляет нужную функциональность следующему («вышележащему») уровню.
На рисунке ниже представлена схема СЭД «Кодекс: Документооборот», в которой отображено API для внешних систем, а также для внутренних в данной СЭД.

API библиотеки функций и классов включает в себя описание сигнатур и семантики функций.

Сигнатура функции

Сигнатура функции — это часть общего объявления функции, позволяющая средствам трансляции идентифицировать функцию среди других. В различных языках программирования существуют разные представления о сигнатуре функции, что также тесно связано с возможностями перегрузки функций в этих языках.
Например, в языке программирования C++ простая функция однозначно опознаётся компилятором по её имени и последовательности типов её аргументов, что составляет сигнатуру функции в этом языке. Если функция является методом некоторого класса, то в сигнатуре будет участвовать и имя класса.
В языке программирования Java сигнатуру метода составляет его имя и последовательность типов параметров; тип возвращаемого значения в сигнатуре не участвует.
В СЭД «Кодекс: Документооборот» используется API на основе web-технологий REST-API, на её примере рассмотрим формирование вызова любого GET\POST запроса.

Пример формирования вызова любого GET\POST запроса

Семантика функции

Семантика функции — это описание того, что данная функция делает. Семантика функции включает в себя описание того, что является результатом вычисления функции, как и отчего этот результат зависит. Обычно результат выполнения зависит только от значений аргументов функции, но в некоторых модулях есть понятие состояния. Полным описанием семантики функций является исполняемый код функции или математическое определение функции.
Ниже, для примера, рассмотрена одна из функций СЭД «Кодекс: Документооборот».

/Documents/GetDocLinkedObjects GET
Возвращает список связанных документов по переданному идентификатору.

Таблица 1 — Идентификатор документа

Возвращаемое значение – список связей с документом.

Таблица 2 — Список связей с документом

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

Документация API — это техническая (программная) документация, в которой указано как использовать API.
При этом эту документацию нужно поддерживать в актуальном стоянии чаще, чем любую другую. Ведь от актуальности документации API зависит качество разработки продукта. Однако, есть еще проблема разработки самого API системы. Любая система развивается, добавляются функции, изменяются существующие вызовы и методы. Но необходимо помнить о том, что с нашей системой могут быть интегрированы другие системы. И если изменения затронут API, то такая интеграция «развалится», при следующем обновлении произойдёт нарушение механизмов взаимодействия. Поэтому в документировании API можно выделить две основные проблемы:

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

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

Способы создания документации API

Одни из самых популярных спецификаций — это RAML, Swagger и API Blueprint.
Например, если программирование Системы происходи в MS Visual Studio, то в ней автоматически генерируется Xml (представлена на картинке ниже), с помощью которой уже можно создать в любой другой спецификации документацию API.

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

Swagger

Для учебных целей можно открыть Swagger Editor, в котором можно попробовать создавать документацию API.
Сайт: http://editor.swagger.io/
Swagger Editor состоит из двух блоков: код (слева), документация API (блок справа (зависит от блока слева)).

Типы аннотаций, использованные для описания методов:

Документация API

В Swagger генерация происходит автоматически.
Полученная документация содержит описание всех типов данных, возвращаемых API, список доступных методов c подробным описанием.

Описание метода API содержит его url, описание всех параметров, а также все варианты ответов. Т.к. мы ссылались на модель Post в описании ответа, мы можем видеть ссылку на эту модель и даже пример ответа API, сгенерированный на основании описания модели.

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

Источник

Документирование API — документация из тестов

Пост в продолжение темы экспериментальных решений, откуда будет переиспользован код для примера. В прошлом посте я затронул тему, как можно написать тесты на простой сервис, когда он выступает в роли черного ящика и из кода теста у нас нет прямого доступа к коду тестируемой программы. Ещё раз остановлюсь на том, что тестируемый сервис был реализован на языке Go, а тесты к сервису на языке Ruby и фрэймворке для тестирования RSpec. Стэк был выбран из собственных предпочтений и не имеет ключевого значения к рассматриваемой теме. В этой статье хочу рассмотреть вопрос документирования API, вновь используя не совсем стандартное решение.

Существует несколько основных подходов к написанию документации:

Теперь кратко рассмотрим несколько менее распространенных способов составления (и использования) документации:

Ещё хочу отметить, что такие протоколы как GRPC, Apache Thrift и подобные фактически заставляют сначала написать (а потом и поддерживать) машиночитаемое описание API и только потом писать реализацию, что несомненно может нести некоторый раздражающий эффект от необходимости постоянной правки файлов с описанием протокола, но с другой стороны мы всегда уверены, что как минимум описание сигнатур соответствует реальности.

И последний (в данном тексте) способ получения документации:

На просторах сети были найдены руби гемы rspec-rails-swagger и rswag. Оба к сожалению имеют хоть и минимальную, но привязку к rails. Гемы имеют вполне подробную документацию с примерами и достаточно простой код. В качестве эксперимента я отвязал гем rspec-rails-swagger от Rails и подключил к существующим функциональным тестам.

Описание теста для генерации документации к методу выглядит следующим образом:

Данный код запускает тесты на исполнение и используют расширение синтаксиса Rspec для указания мета информации которая будет использована при генерации swagger файла.

Запускаем rspec через длинную команду:

В конечном итоге мы имеем функциональные тесты на фрэймворке Rspec, попутно сгенерировав swagger документацию, из которой можно быстро получить болванку API клиента для любого другого языка программирования. Полный листинг примера.

Источник

Пишем документацию API при помощи RAML

Удобство работы с любым API во многом зависит от того, как написана и оформлена его документация. Cейчас мы ведём работу по стандартизации и унификации описания всех наших API, и вопросы документирования для нас особенно актуальны.
После долгих поисков мы решили оформлять документацию в формате RAML. Так называется специализированный язык для описания REST API. О его возможностях и преимуществах мы расскажем в этой статье.

Почему RAML

Как нужно документировать API? Вопрос этот не так прост, как может показаться на первый взгляд.
Первый и самый простой вариант, который приходит на ум — представить описание к API в виде обычного текстового документа. Так делают очень многие (в том числе и очень известные компании). Мы тоже не раз пользовались этим способом. При всей своей простоте он обладает следующими недостатками:

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

Конечно, YAML гораздо удобнее, чем JSON. Но и его использование сопряжено с определёнными трудностями. Дело в том, что в описаниях API всегда имеются повторяющиеся элементы (например, схема ответа, которая может быть одинаковой для разных типов HTTP-запросов), которые приходится всякий раз прописывать вручную. Вот если бы можно их было раз и навсегда прописать в отдельном файле и ссылаться на него в случае небходимости… Но, увы, пока что такой возможности нет.

Что касается формата Markdown (он используется, например, в API BluePrint), то предназначен в первую очередь для оформления текста, а не для использования в качестве основы для генерирования. Приспособить его под документирование API очень сложно. По этой же причине не привели к каким-либо заметным результатам попытки cоздать формат описания API на базе XML — например, язык WADL (Web Application Desription Language), разработанный компанией Sun Microsystems ещё в 2009 году, но так и не получивший широкого распространения.

Создатели проекта RAML (эта аббревиатура означает RESTful API Modeling Language — язык для моделирования REST API ) предприняли попытку разработать язык, предназначенный исключительно для описания API и исправить недочёты, свойственные другим форматам. Первая версия спецификации RAML была опубликована в 2013 году. Основным разработчиком RAML является компания MuleSoft; в проекте также принимают участие представители таких известных компаний, как Cisco, PayPal, ВoxInc. и других.

Краткое введение в RAML

Структура документа

Файл спецификаций на RAML состоит из следующих структурных элементов:

Вводная часть

Каждый документ на RAML начинается с вводной части, которая включает четыре обязательных элемента:

Вводная часть может также включать различную дополнительную информацию — например, сведения об используемом протоколе для связи с API:

Можно во вводной части прописать и метаданные файла документации:

Схемы безопасности

Чтобы начать работать с любым API, нужно пройти процедуру авторизации. Она может осуществляться разными способами: через OAuth, с помощью токенов, либо посредством простой HTTP-аутентификации. Для описания этой процедуры в RAML используются схемы безопасности (security schemes).
Рассмотрим в качестве примера, как описывается авторизация с использованием протокола OAuth2:

Приведённый фрагмент содержит следующую информацию:

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

Почитать более подробно о схемах безопасности и ознакомиться с конкретными примерами можно здесь(раздел Security).

Объекты и методы

Далее перечисляются основные объекты и пути к ним, а также HTTP-методы, которые используются с этими объектами:

В приведённом примере описывается API, с помощью которого можно работать с документами. Мы можем скачивать документы на локальную машину (GET), изменять cуществующие документы (PUT) и загружать новые (POST). С каждым отдельным документом () мы можем также выполнять следующие операции: загрузка на локальную машину (GET) и удаление (DELETE).
HTTP-заголовки, используемые с тем или иным методом, описываются при помощи свойства headers, например:

Обратите внимание на свойство required: оно указывает, является ли заголовок обязательным (true) или необязательным (false).
В описании объектов и методов могут использоваться многочисленные дополнительные параметры. Рассмотрим следующий пример:

Здесь мы указываем, что каждый из документов, доступ к которым можно получить через API, имеет собственный идентификационный код в виде строки (type: string), а также описываем формат этого кода с помощью регулярных выражений.

Свойства description, type и pattern можно использовать и в описаниях методов, например:

В описании метода POST мы указываем параметры, которые нужно передать в теле запроса для добавления нового документа: ID, имя и имя автора. Каждый из этих параметров является строкой (type: string). Обратите внимание на свойство required: оно указывает, является ли параметр обязательным (true) или необязательным (false).

Для каждого метода можно прописать индивидуальную схему безопасности:

Query-параметры

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

Профили

Чтобы избежать лишних повторений в описаниях, в RAML используются профили (traits), которые прописываются во вводной части документа:

В дальнейшем к профилю можно обращаться при описании любых методов:

Более подробно о профилях и особенностях их использования можно почитать в официальной документации (раздел Traits).

Описание ответа

В описании ответа обязательно указывается его код. Также в описание можно добавить схему (schema) — перечисление входящих в ответ параметров и их типов. Можно также привести пример конкретного ответа (example).

Визуализация и генерация документации

RAML2HTML и другие конвертеры

Несмотря на то, что RAML — формат относительно новый, для него уже разработано достаточное количество конвертеров и парсеров. В качестве примера можно привести ram2htmtl, генерирующий на основе описания в формате RAML статическую HTML-страницу.
Устанавливается он при помощи менеджера пакетов npm:

Чтобы сконвертировать RAML-файл в HTML, достаточно выполнить простую команду:

Поддерживается возможность создания собственных шаблонов для HTML-файлов (подробнее об этом см. в документации на GitHub по ссылке выше).
Из других конвертеров рекомендуем также обратить внимание на RAML2Wiki и RAML2Swagger.

API Designer

Компания Mulesoft (один из активных участников проекта RAML) создала специальный онлайн-инструмент, с помощью которого можно упростить работу по написанию документации и последующему тестированию API. Называется он API Designer.
Чтобы начать им пользоваться, нужно сначала зарегистрироваться на сайте. После этого можно приступать к работе. API designer предоставляет, во-первых, удобный интерактивный редактор для написания документации онлайн, а во-вторых — платформу для тестирования.
Выглядит всё это так:

В правой части страницы автоматически генерируется интерактивная документация. Здесь же можно и протестировать API: для этого достаточно просто развернуть описание нужного запроса и нажать на кнопку Try it.

API Designer позволяет также загружать RAML-файлы с локальной машины. Поддерживается импорт файлов описаний API для Swagger.
Кроме того, API Designer хранит статистику тестовыx запросов к API.

API console

API console — полезный инструмент, разработанный всё той же компанией MuleSoft. С его помощью можно прямо в браузере генерировать документацию к API. Файлы спецификаций можно как загрузить с локальной машины, так и указать ссылку на внешний источник:

В состав API Console входит несколько файлов-образцов, представляющих собой описания API популярных веб-сервисов: Twitter, Instagram, Box.Com, LinkedIn. Мы попробовали сгенерировать на основе одного из низ документацию — выглядит вполне симпатично:

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

Заключение

В этой статье мы рассмотрели основные возможности RAML. Его несомненными преимуществами являются простота и логичность. Надеемся, что в скором будущем RAML получить ещё более широкое распространение и займёт достойное место в ряду инструментов для документирования API.
Если у вас есть вопросы — добро пожаловать в комментарии. Будем также рады, если вы поделитесь собственным опытом использования RAML на практике.

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

Источник