документы по 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). С каждым отдельным документом (
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 при разработке
Многие из нас при выполнении своих обязанностей на работе сталкиваются с необходимостью заглянуть в какой-либо справочник, который даст нам ответ на вопрос. Если вы пользователь 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, разберитесь в этом – и карьерный рост вам обеспечен! Получить первое представление вам поможет эта статья. Автор – Лоис Паттерсон (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, знайте, что это требует такого же тщательного внимания к деталям, которое требуется и от технического писателя в целом. Вы должны предоставлять и бизнес-контекст высокого уровня, и при этом мало деталей по реализации. Вы можете заявить себя как члена команды разработки и вовлечь всю команду в процесс улучшения документации.