что такое 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 на практике.

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

Источник

Документирование 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 «Руководство для технических писателей»

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

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

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

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

О REST API

REST API используют запросы и ответы по протоколу HTTP

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Видео записи

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

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

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

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

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

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

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

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

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

Источник

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

Что такое API, для чего используется, зачем и как начать его документировать, какие инструменты использовать, как взаимодействовать с коллегами, какие существуют основные принципы. Очень полезная статья для технических писателей, которые хотят роста. Начинайте документировать API, разберитесь в этом – и карьерный рост вам обеспечен! Получить первое представление вам поможет эта статья. Автор – Лоис Паттерсон (Lois Patterson), технический писатель API из компании Global Relay (Канада).

Тяжело отследить, сколько раз API (Application Programming Interfaces, интерфейсы программирования приложений) сопровождают нашу жизнь каждый день или даже каждый час. Когда проходит ваша транзакция в PayPal или когда вас подбирает водитель Uber, само по себе API невидимо, и это более чем типично для пользовательского программного обеспечения. API используется даже тогда, когда вы встраиваете YouTube-видео в запись WordPress. При наличии сотен тысяч общедоступных API, доступных широчайшему кругу пользователей, компании находятся под большим давлением, чтобы их API были легки и удобны для использования. Не будет сюрпризом то, что рост количества вакансий, связанных с документированием API, огромен — он показывает разогретый рынок для технических писателей, которые специализируются на документировании API.

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

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

Так чего хотят пользователи API?

Что мы всегда говорим новым (и старым) техническим писателям? Узнайте ваших пользователей… и пишите c расчётом на этих пользователей. Поставьте себя на их место и поймите, что им необходимо знать, чтобы выполнить свою задачу.

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

Начните с разработки API

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

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

Как выглядит связная разработка? Давайте обратим внимание на REST API, которые наиболее популярны для использования на массовом рынке. REST (Representational State Transfer, «передача состояния управления») представляет собой набор принципов разработки API, которые зарекомендовали себя как исключительно эффективные в широком спектре очень разных API.

В типичном REST API набор существительных (объектов) взаимодействует с ограниченным набором глаголов (GET, PUT, POST, DELETE). Параметры каждого существительного должны следовать схожим шаблонам и соглашениям. Параметры должны иметь такие типы данных, которые имеют смысл и связаны между собой. Если параметр userID — строка, а customerID — число, вы введёте пользователя в заблуждение. Действия глаголов должны быть связными для всех объектов.

Pearson предлагает хороший учебник по разработке REST API, который может ответить на большинство первоначальных вопросов.

Первый опыт использования вашего API

Если вы новый пользователь сложного нового продукта, что вы в первую очередь захотите сделать? Успешно использовать его. Как указал мне эксперт по разработке документации Том Джонсон (Tom Johnson), пользователь должен иметь возможность получить быстрый успех с помощью скорейшего продвижения к «Привет, мир» при использовании API. Searchify, например, содействует использованию своего продукта с помощью этой простого урока «Привет, мир», а затем переходит к более сложным урокам.

Обратите внимание на тщательное конструирование шагов и как пользователю сообщают обо всех необходимых условиях для завершения урока. Урок позволяет пользователям выбрать язык программирования.

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

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

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

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

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

Давайте рассмотрим несколько инструментов, которые вы можете использовать.

Основные принципы

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

Это требование по привлечению разработчиков к созданию документации означает, что вам нужен переносимый формат, который может быть доступен для любого текстового редактора. У вас может быть один разработчик, который работает в emacs, другой в vim, а третий в SublimeText, и никто из них не хочет изучать новый текстовый редактор. Мы все знаем, насколько привязанными могут быть технические писатели к собственным инструментом, будь то Microsoft Word или MadCap Flare, и с разработчиками то же самое. К счастью, файлы, создаваемые в различных текстовых редакторах, полностью совместимы в отличие от проприетарных инструментов. Документация API может создаваться в виде текстовых файлов, а затем обрабатываться в генераторе статичных сайтов для создания привлекательных веб-сайтов или PDF. Ниже указаны несколько текстовых редакторов, которые, как мне известно, популярны среди различных групп разработчиков:

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

Markdown с генератором статичных сайтов

Markdown — популярный и несомненно вездесущий формат в наши дни. Markdown — простой язык разметки, который вы можете использовать в любом текстовом редакторе. Если у вас есть файлы, созданные в Markdown, вы затем используете генератор статических сайтов, например, Jekyll, приложение, которое преобразует файлы, созданные в Markdown, в форматы HTML, PDF и другие. Если ваша документация в формате Markdown размещена на Github, ваши документы автоматически преобразуются в HTML без каких-либо действий с вашей стороны (хотя вы можете настроить отображение).

Вы можете научиться писать на Markdown за минуты. Это просто. Разработчики из вашей команды знают и любят Markdown. Использование Markdown помогает вам убрать барьеры между командой работки и командой документирования.

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

Разметка reStructuredText с генератором статических сайтов Sphinx

reStructuredText похож на Markdown, но предоставляет больше функций и отчасти связан с разработкой в Python. Я ценю простоту, с которой вы можете делать вставки из файлов, создавать библиографические ссылки, использовать LaTeX для математических выражений и создавать связи между множеством наборов документации. Несмотря на то, что reStructuredText немного более сложен, чем Markdown, а установка вместе с генератором статических сайтов Sphinx также может принести сложности, большинство пользователей также находят его простым в использовании. Многие пользователи выбирают реализацию reStructuredText и Sphinx, предлагаемую ReadTheDocs, как описано здесь:

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

Несмотря на то, что Sphinx наиболее популярен, также доступен другой генератор статических сайтов для restructuredText — Nikolai.

RAML, Swagger и API Blueprint

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

Вы можете увидеть более глубокие примеры с помощью Watson API и их представлений Swagger. Watson — движок искусственного интеллекта, который выигрывает у игроков-людей в Jeopardy, но используется во множестве других контекстов.

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

Какие документы и контекст необходимо включать?

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

Йогешвор Срикришнан (Yogeshwar Srikrishnan), бизнес-архитектор в Rackspace, замечает, что «Наиболее важная часть опыта для разработчика, который потребляет API — документация для разработчика». В его статье о документировании REST API для Dzone подробно изложены многие важные аспекты документации для разработчиков.

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

Зажигайте пользователей креативно. Например, с API Интернета вещей (IoT) некоторые пользователи думают о путях связи элементов, о которых вы и представить не могли, что они могут работать вместе. Знаете ли вы, что у Roomba есть API и что вы можете использовать это API, чтобы превратить Roomba в музыкальный инструмент?

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

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

Новый пользователь Twitter API может начать с самого начала — набора ЧаВо.

Установка и настройка

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

Делайте обновления API удобными для пользователей

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

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

Выкладывать ли документацию в Интернет

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

Расположение документации онлайн на Github демонстрирует, что ваша компания ищет подходы к пользователям-разработчикам. Вы можете получать прямую обратную связь от разработчиков о том, что корректно и полезно, а что нет. Например, PayPal провёл серьёзную работу над контентом, доступным на Github, включая документацию. И быстрый взгляд на сайт Github, раздел SDK для PayPal для Android показывает, что документы были обновлены семь дней назад (на данный момент).

Тестируйте, тестируйте, тестируйте!

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

Некоторые обычные инструменты для тестирования REST API включают в себя curl и Postman. Вам может потребоваться помощь вашей команды разработчиков, чтобы заставить их работать у вас, но ваша команда, скорее всего, уже использует эти или похожие инструменты. С помощью curl или Postman вы создаёте запрос, который хотите протестировать, и проверяете, что возвращается корректный ответ. Типичным тестом может быть проверка различных комбинаций параметров, чтобы убедиться, что они работают корректно вместе.

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

В заключение

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

Источник