Connect with us

Статьи

Xsolla: как сделать документацию API всегда актуальной

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

Xsolla

Опубликовано

/

     
     

Xsolla — международная компания, которая работает со множеством разработчиков и издателей из США, России, Южной Кореи, стран СНГ. Чтобы предоставить самую свежую информацию для быстрой интеграции клиентам, команда Xsolla придумала инновационный инструмент автоматической генерации сопроводительной документации. О том, как работает данная система, рассказывает Тимур Саттаров — ведущий разработчик компании.

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

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

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

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

Долой человеческий фактор

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

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

Аннотации в Symfony

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

В нашей реализации мы будем хранить в аннотациях всё, что нужно для формирования документации. Работу с аннотациями обеспечат FOSRestBundle и NelmioApiDocBundle.

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

Пример аннотаций в Xsolla API

Пример аннотаций в Xsolla API

Для валидации входных параметров мы используем формы Symfony. Описание параметров и их типы также указаны в коде.

Пример кода Xsolla API

Пример кода Xsolla API

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

Получение ответов от API

Еще одна особенность подхода Xsolla в том, что для каждого метода на основе URL и входных данных система автоматически выполняет метод с тестовыми входными данными и фиксирует ответ от API, который попадёт в документацию. Таким образом, при генерации документации мы ещё раз проверяем формат вводных данных. Это лишний раз позволяет гарантировать, что документация на 100% соответствует коду.

Генерация Markdown

Для генерации автоматической документации по коду мы использовали NelmioApiDocBundle.

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

Совсем без писанины не обошлось, конечно. Статические части документа API Reference (например, вступления к некоторым разделам) остаются неизменными, и их обязательно должен написать специалист. Компьютер на такое не способен пока ещё.

Пример использования Markdown

Пример использования Markdown

В Markdown попадает всё, что впоследствии окажется в документации: URL и описания методов, входные параметры, примеры выполнения команд с использованием нескольких технологий (на данном этапе HTTP и cURL).

Markdown позволяет легко контролировать изменения, а также добавлять разделы со статическим содержимым. Удобно и быстро.

Генерация HTML

Изначально генерировали документацию на основе slate, но впоследствии реализовали собственное решение.

Полученные в Markdown данные мы преобразовываем в HTML подсистемы, написанные с использованием node.js и находящиеся под управлением gulp.

Формирование HTML на основе Markdown реализовано с использованием библиотек animate.css, bourbon, lodash, normalize-css, retina.js, underscore.

Пример отображения документа в HTML

Пример отображения документа в HTML

Deployment

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

Результаты работы можно увидеть на developers.xsolla.com.

Заключение

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

Комментарии
Если вы нашли опечатку - выделите ее и нажмите Ctrl + Enter! Для связи с нами вы можете использовать info@apptractor.ru.
Advertisement
Click to comment

You must be logged in to post a comment Login

Leave a Reply

Статьи

Шесть киберугроз 2018 года

Мартин Джайлс из MIT Technology Review описал шесть главных угроз кибербезопасности, которые возникнут в 2018 году.

Анна Гуляева

Опубликовано

/

Больше крупных утечек данных

В 2017 произошла кибератака на бюро кредитных историй Equifax, которая привела к краже номеров социального страхования, дат рождения и других данных о половине населения США. Эта утечка данных стала напоминанием о том, что хакеры ищут крупные цели. Поэтому в 2018 в их поле зрения попадут другие компании с важной информацией. Марк Гудман, эксперт по безопасности и автор Future Crimes, считает, что популярными целями будут компании, хранящие информацию о таких вещах, как персональные привычки в веб-серфинге. «Эти компании не регулируются, и если произойдет одна утечка, то под угрозой окажутся все», — говорит он.

Программы-вымогатели в облаке

За последние 12 месяцев мы увидели волну атак вирусов-вымогателей на такие цели, как Национальная служба здравоохранения Великобритании, легкорельсовую транспортную сеть Сан-Франциско и большие компании, вроде FedEx. Вымогатель — это довольно простая форма вредоносной программы, которая попадает в компьютер через бреши в защите и шифрует файлы, используя сложное шифрование. Затем хакеры требуют деньги в обмен на ключи для расшифровки данных. Жертвы часто платят, особенно если зашифрованный материал не имел резервной копии.

Это делает вымогатели популярными среди хакеров, которые часто требуют плату в криптовалюте, которую сложно отследить. Некоторые особо вредоносные вирусы, например, WannaCry, заразили тысячи компьютеров. Крупной целью в 2018 будут компании облачных вычислений, которые хранят огромное количество данных для организаций. Некоторые из них также владеют сервисами для потребителей, например, email или фото-библиотеками. Крупнейшие облачные операторы, то есть Google, Amazon и IBM, нанимают лучших специалистов по цифровой безопасности, поэтому их взломать будет непросто. Но меньшие компании более уязвимы, и даже мельчайшая лазейка может привести к огромным выплатам хакерам.

ИИ как оружие

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

Примером может быть фишинг, для которого используются таргетированные сообщения, которые обманывают людей, чтобы те установили зловредную программу или поделились личными данными. Модели машинного обучения теперь равны людям в искусстве создания убедительных фальшивых сообщений, и они могут придумывать гораздо больше таких посланий. Хакеры будут использовать это для фишинговых атак. Вероятно, что они будут использовать ИИ для создания программ, которые будут ещё лучше обманывать «песочницы», программы, которые пытаются уловить вредоносный код до его развертывания в системах компаний.

Физические кибератаки

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

Майнинг криптовалют

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

Майнинг криптовалют требует большой вычислительной мощности для решения сложных математических проблем. Как отметил мой коллега Майк Оркатт, это подталкивает хакеров к взлому миллионов компьютеров для использования их для подобной работы. Недавние случаи варьируются от взлома публичного Wi-Fi в Starbucks в Аргентине до атаки на «Транснефть». Майнинг валют растет, растет и искушение взломать больше компьютерных сетей. Если хакеры нацелятся на больницы, аэропорты и другие чувствительные локации, потенциальный сопутствующий ущерб может быть пугающим.

Взлом выборов (опять)

Фейковые новости — это не единственная угроза стране, в которой проходят выборы. Существует риск кибератак на сам процесс выборов. В США в ноябре пройдет промежуточные выборы, поэтому над устранением уязвимостей сейчас ведется упорная работа. Но у потенциальных взломщиков существует множество целей: от электронных списков избирателей до автоматов для голосования и программ, обрабатывающих результаты выборов.

Так как эти и другие риски будут расти в 2018, вырастут и штрафные меры для компаний, которые не смогут с ними эффективно справляться. 25 мая в Европе вступят в силу «Общие положения о защите данных», GDPR. Это первое крупное изменение в правилах защиты данных в регионе за более чем 20 лет, и GDPR будут требовать от компаний сообщать об утечках данных регулирующим органам и информировать об утечках клиентов в течение 72 часов после обнаружения взлома. Нарушение будет караться штрафом до 20 миллион евро или 4% от дохода компании, смотря что больше.

Тот факт, что Uber скрывал крупную кибератаку в прошлом году, вероятно, вызовет ужесточение правил и в США. Это значит, что у юристов в 2018 будет столько же работы, сколько и у хакеров.

 

Комментарии
Продолжить чтение

Дизайн и прототипирование

Создание шрифта с нуля за 24 часа

Графический дизайнер Джеймс Барнард бросил себе вызов – он захотел за 24 часа создать шрифт и отправить его в Google Fonts. Как он это сделал и что узнал в процессе — в нашем переводе статьи Джеймса.

Анна Гуляева

Опубликовано

/

Я большой фанат One Day Builds Адама Сэвиджа. В начале дня у него есть только материалы, а в конце он становится обладателем чего-то, что он хотел.

Поэтому я бросил себе вызов: создать с нуля абсолютно новый шрифт и отправить его в Google Fonts за 24 часа.

В старом блокноте у меня были эскизы нескольких букв. Я хотел создать узкий шрифт без засечек, который можно будет использовать на постерах или на других больших изображениях. Во время работы в Men’s Health я использовал шрифты вроде Tungsten или Heron, которые выглядят ужасно в тексте, но отлично смотрятся в заголовках или промоматериалах (которые и были моей основной работой). Это был стиль, который я и хотел создать.

Очень грубые наброски

13:00, среда

Я отправился в Adobe Illistrator с двумя-тремя буквами, которые были у меня в эскизах. Я создал сетку из пяти строк – для линии нижних выносных, базовой линии, линии строчных, линии прописных и линии верхних выносных букв. Затем я определил ширину прописных букв и толщину основного штриха.

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

  • Линия строчных = 2 × высота линии верхних выносных / высота линии нижних выносных
  • Ширина основного штриха = ¼ ширины прописной буквы
  • Ширина строчной буквы = ¾ ширины прописной буквы

Вот как это выглядит на иллюстрации

Сначала я создал буквы O и B. Я решил, что эти буквы будут иметь не форму овала, а форму скругленного угла. Многие буквы будут выглядеть, как высокий прямоугольник, но O, B и D будут иметь скругленные углы вместо овалов.

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

Мой шрифт был очень простым, но с одним «украшением». Любая апертура, то есть, срез концов полуовала, должна была быть отрезана под углом. Самыми сложными буквами стали G и K.

Затем я приступил к строчным буквам. Это было сложнее, но с установленными правилами работать было проще. Я использовал больше «украшений», особенно в верхних выносных и нижних выносных элементах. Самыми сложными стали буквы f, g, a и e, так как они были абсолютно новыми.

21:00, среда

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

Утро четверга

Утром я довольно быстро закончил цифры от 0 до 9 и начал создавать файл с шрифтом. Это было совершенно новым опытом. Мой знакомый каллиграф Иэн Барнард посоветовал для этого программу Glyphs. Я скачал программу, посмотрел несколько обучающих видео и понял, что неверно создал файл в Illustrator. Поэтому мне пришлось вставлять каждый символ вручную и подгонять его под правила программы.

10:00, четверг

Я начал заниматься интервалами и кернингом. Это было ужасно долго. Прежде чем заняться этим, нужно освоить множество сочетаний клавиш в программе. И перед кернингом вам нужно сделать интервал как можно ближе к тому, что вы хотите видеть в итоге. Для этого нужно измерить ширину отверстия в букве О и разделить ее на три. Такой интервал стоит поместить слева и справа от буквы.

11:00, четверг

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

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

Затем я конвертировал текст в прописные буквы и сделал то же самое для них.

12:59, четверг

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

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

Название шрифта? Odibee Sans (произносится как oh-dee-bee), то есть, One Day Build — ODB.

Заключение

Я отправил Odibee Sans в Google в мае 2017, и он все ещё находится в очереди на добавление. Команда предложила мне пока уделить время дизайну шрифта, хотя они признали, что это противоречит духу проекта.

Я поработал над шрифтом ещё один день. Я добавил все нужные знаки, а также внёс изменения примерно в 30 символов.

Более того, сейчас в шрифте существует более 1500 кернинговых пар, что стало значительным улучшением шрифта. А также я создал сайт: odibeesans.com.

Комментарии
Продолжить чтение

Разработка

Как сделать собственный VR-шлем за $100

Максим Кутте, 16-летний разработчик, создал свой open source шлем виртуальной реальности.

Леонид Боголюбов

Опубликовано

/

Меня зовут Максим Кутте. Мне 16 лет и я со своими друзьями, Йонасом Сессоном и Габриелем Комбе, сделал свой собственный шлем виртуальной реальности. Он стоил нам всего 100 долларов.

Благодаря моему учителю, я начал программировать в 13. Каждый понедельник и вторник вместо кафе я с друзьями ходил в его класс.

Я потратил один год на создание простой 8-битной операционной системы и участие в конкурсе роботов.

Затем я заинтересовался виртуальной реальностью. И мы с друзьями решили, что неплохо было бы создать собственный мир в VR, в котором мы могли бы проводить время после школы. Но Oculus  тогда стоил 700 долларов, и мы решили создать собственный шлем.

VR для всех

Напечатанная на 3D принтере запчасть

Причиной всего стало аниме под названием Sword Art Online. Его главный герой находится в ролевой виртуальной реальности – и так я влюбился в VR. Я хотел понять все ее аспекты.

Я купил самые дешевые компоненты, которые мог, и начал, изучая основы физики и математики виртуальной реальности (правильное ускорение, первообразные, кватернионы…) А потом мы заново изобрели VR. Я написал WRMHL, а затем с Габриелем FastVR. Объединив все это вместе, мы получили гарнитуру стоимостью $100.

Полностью открытая гарнитура для VR и комплект для разработки

Чтобы ускорить время разработки, мы сделали FastVR – SDK с открытым исходным кодом для разработчиков, который легко понять и кастомизировать. Он работает следующим образом:

  • Главный компьютер шлема вычисляет его позицию в пространстве
  • Позиция из шлема отправляется в WRMHL и часть вычислительной мощности процессора тратится на обработку этого сообщения
  • Затем FastVR извлекает данные и использует их для рендеринга VR-игры

Все, что вам надо – сделать на основе открытых исходников шлем.

Почему open source

Я хочу сделать VR мейнстримом. Поэтому я обратился к Уссаме Аммару, одному из соучредителей The Family. Я обсудил с ним создание компании и запуск на Kickstarter.

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

Мы отправились в Кремниевую долину, и Уссама познакомил меня с главным архитектором в Oculus, Атманом Бринштоком. И они дали мне ценный совет: сделай все это open source.

Следующий шаг

Есть еще много технических моментов, которые мы хотим улучшить.

Сейчас мы работаем над автономной VR-гарнитурой –  у нас уже есть как упрощенная версия с более дешевым 3D-трекингом.

Все это мы скоро выпустим.

Как начать

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

 

Комментарии
Продолжить чтение

Дизайн и прототипирование

Ультрафиолет стал цветом 2018 года: что он значит?

В конце каждого года институт цвета Pantone выбирает цвет, который будет определять наступающий год. В 2018 году таким цветом стал Ultra Violet — ультрафиолетовый. Какую символику несет в себе этот цвет и универсальны ли цветовые коды для людей по всему миру?

Анна Гуляева

Опубликовано

/

В конце каждого года институт цвета Pantone выбирает цвет, который будет определять наступающий год. Этот цвет не является отражением модных тенденций, а символизирует изменения в обществе. В 2018 году таким цветом стал Ultra Violet — ультрафиолетовый. Какую символику несет в себе этот цвет и универсальны ли цветовые коды для людей по всему миру?

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

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

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

Но это не единственное значение ультрафиолетового. Он имеет большое значение в качестве цвета, который использовался в символике движения суфражисток, для которых он символизировал преданность и упорную верность своей цели. Помимо этого, ультрафиолетовый является важным символом борьбы за права ЛГБТК-людей. Фиолетовый — это смесь голубого и розового цветов, несущих гендерную окраску, и он отражает размытие границ гендеров. Ультрафиолет позволяет нам увидеть вещи, невидимые в обычном освещении, и этот смысл действительно важен для 2018 года, как в стремлении к многообразию и равноправию разных групп общества, так и в напоминании о творческом потенциале людей и возможностях человеческого мышления.

Комментарии
Продолжить чтение

Наша рассылка

Каждому подписавшемуся - "1 час на UI аудит": бесплатный ускоренный курс для разработчиков!

Нажимая на кнопку "Подписаться" вы даете согласие на обработку персональных данных.

Вакансии

Популярное

X

Спасибо!

Теперь редакторы в курсе.