Документирование 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 запроса

//на вход принимаются url запроса, метод (GET/POST), токен, и объект, который необходимо
//передать, если это POST
public static byte[ ] CreateRequest(string url, string method, string token, Object obj)
{
	HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
	request.Method = method;
	//Помещаем токен в заголовок
	request.Headers.Add(«Token», token);
	// Если POST – записываем передаваемый объект
	if (request.Method == «POST»)
	{
		UTF8Encoding encoding = new UTF8Encoding();
		string jsonString = JsonConvert.SerializeObject(obj);
		var bytes = encoding.GetBytes(jsonString);
		request.ContentType = «application/json»;
		request.ContentLength = bytes.Length;
		using (var newStream = request.GetRequestStream())
		{
			newStream.Write(bytes, 0, bytes.Length);
			newStream.Close();
		}
	}
	try
	{
		//Получаем ответ от сервиса
		HttpWebResponse httpWResponse = (HttpWebResponse)request.GetResponse();
		using (MemoryStream mstr = new MemoryStream())
		{
			httpWResponse.GetResponseStream().CopyTo(mstr);
			//возвращаем полученный с сервиса объект в виде массива байт
			return mstr.ToArray();
		}
	}
	catch (WebException ex)
	{
		//обрабатываем исключения
		var stCode = ((HttpWebResponse)ex.Response).StatusCode;
	}
	return null;
}

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

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

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

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

Параметр Тип Описание
uid Guid Идентификатор документа

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

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

Свойство Тип Описание
DocUID Guid Идентификатор связанного элемента
DirectionType DirectionType Тип связанности (тип подчинения)
LinkType Integer Идентификатор типа связи (из справочника LINK_TYPES)
LinkTypeName String Наименование типа связи
OperatorUID Guid Идентификатор автора, создавшего связь

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

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

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

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

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

  1. Пример полного запроса.
  2. Примеры ожидаемого ответа.
  3. Список кодов ошибок.
  4. Удобный для поиска Web–интерфейс.
  5. Предупреждения об изменении версии и расписание устаревания.

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

  1. Создать текстовый документ.
    Это, конечно, самый простой вариант, в котором можно сделать максимально подборные описания, но такой документ сложно поддерживать в актуальном состоянии, на его создание уйдёт куча времени, да и использовать его в других сферах (например, тестирование) нельзя.
  2. Создать документацию с помощью специализированных программ (спецификаций).
    Их нельзя сделать такими подробными, как тестовый документ, но зато можно настроить автогенерацию (изменение кода приложения документации автоматически с учётом изменений), которая позволит быть документации 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 (блок справа (зависит от блока слева)).

 

 

Код

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

  • Get — означает, что для доступа к методу должен использоваться http-метод GET. Существуют аналогичные аннотации для всех http-методов: Post, Put и другие.
  • Parameter — используется для описания параметров метода.
  • Response — используется для описания ответа API.
  • Schema — используется для описания формата выходных данных.

 

 

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

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

 

 

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

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

DocPlace 2019-05-28

Добавить комментарий