В динамичном мире микросервисов измениться может все что угодно — любой компонент можно переписать на другом языке, используя иные фреймворки и архитектуру. Неизменными должны оставаться лишь контракты, для того, чтобы с микросервисом можно было взаимодействовать извне на некой постоянной основе, вне зависимости от внутренних метаморфоз. И сегодня мы расскажем о нашей проблеме выбора формата описания контрактов и поделимся найденными артефактами.
Рубрика «swagger» - 2
Так все-таки RAML или OAS (Swagger)?
2019-09-11 в 5:15, admin, рубрики: OAS, RAML, swagger, Блог компании Acronis, контракты, микросервисы, Облачные вычисления, облачные сервисы, Совершенный код
Самодокументируемый REST сервер (Node.JS, TypeScript, Koa, Joi, Swagger)
2019-05-02 в 10:21, admin, рубрики: api, joi, koa, node.js, open source, openapi, rest, swagger, TypeScript
Про преимущества и недостатки REST написано уже довольно много статей (и еще больше в комментариях к ним) ). И если уж так вышло, что вам предстоит разработать сервис, в котором должна быть применена именно эта архитектура, то вы обязательно столкнетесь с ее документированием. Ведь, создавая каждый метод, мы конечно же понимаем, что другие программисты будут к этим методам обращаться. Поэтому документация должна быть исчерпывающей, а главное — актуальной.
Добро пожаловать под кат, где я опишу, как мы решали эту задачу в нашей команде.
Читать полностью »
Swagger – умная документация вашего RESTful web-API — обзор Junior back-end developer-а для новичков
2018-12-29 в 12:44, admin, рубрики: api, C#, documentation, swagger, tutorial
Предисловие
Команда, в которой я сделала свои первые шаги на поприще написания промышленного кода, занималась разработкой удобного API к функциональности программного продукта на C# (для удобства назовем его, скажем, буквой E), существовавшего уже много лет и зарекомендовавшего себя на рынке с весьма положительной стороны. И здесь вроде бы у юного падавана пока не должно возникать вопросов, однако же представим себе, что ранее вы, скорей всего, конечно, писали собственные web-API, но вряд ли для широкой аудитории, а значит жили по принципу «Сам создал – сам пользуюсь», и если вдруг кого-то бы заинтересовала функциональность вашего API, то вы, наверное, кинули бы ему pdf-файл с подробной инструкцией (по крайней мере я бы сделала именно так). «Где посмотреть функционал апи» — спросила я тимлида ожидая получить ссылку на текстовый документ. «Загляни в Swagger» — ответил он.
Бэкенд для фронтенда, или Как в Яндекс.Маркете создают API без костылей
2018-11-01 в 7:29, admin, рубрики: api, BFF, graphql, node.js, rest, swagger, Блог компании Яндекс, документация, Проектирование и рефакторинг, Разработка веб-сайтовПочему некоторыми API удобнее пользоваться, чем другими? Что мы как фронтендеры можем сделать на своей стороне, чтобы работать с API приемлемого качества? Сегодня я расскажу читателям Хабра как о технических вариантах, так и об организационных мерах, которые помогут фронтендерам и бэкендерам найти общий язык и наладить эффективную работу.
Этой осенью Яндекс.Маркету исполняется 18 лет. Все это время развивается партнерский интерфейс Маркета. Если кратко, то это админка, с помощью которой магазины могут загружать каталоги, работать с ассортиментом, следить за статистикой, отвечать на отзывы и т.д. Специфика проекта такова, что приходится очень много взаимодействовать с различными бэкендами. При этом данные не всегда можно получить в одном месте, из одного конкретного бэкенда.
5+1 случай, когда спецификация REST API играет огромную роль
2018-10-25 в 9:58, admin, рубрики: api, django, http, javascript, node.js, openapi, php, rest, rest api, restful api, ruby on rails, swagger, tinyspec
В этой статье речь пойдёт о написании и поддержке полезной и актуальной спецификации для REST API-проекта, которая позволит сэкономить много лишнего кода, а также серьёзно улучшить целостность, надежность и прозрачность прокта в целом.
Что такое RESTful API?
Это миф.
Серьёзно, если вы думаете, что в вашем проекте RESTful API, вы почти наверняка ошибаетесь. Идея RESTful — в построении API, который во всём соответствовал бы архитектурным правилам и ограничениям, описанным стилем REST, однако в реальных условиях это оказывается почти невозможно.
От API first на Swagger до Single contract на RAML
2018-08-07 в 12:15, admin, рубрики: api, open source, openapi, RAML 1.0, swagger, Анализ и проектирование систем, идея проекта, Программирование, проектирование, Разработка веб-сайтов
Привет, %username%!
Ты наверняка знаешь, что такое API интерфейсы и то, как много от них зависит в твоем проекте. Более того, я так же полагаю, что ты уже знаком с тем, что такое API first подход и знаешь, что Swagger и его Open API являются одними из самых популярных инструментов, помогающих ему следовать.
Но в этой статье я хочу рассказать про подход к реализации API first, концептуально отличающийся от того, что предлагает Swagger и Apiary. Во главе идеи стоит понятие Single contract и возможность его реализации на базе RAML 1.0.
Под катом:
- Краткое описание принципов API first;
- Single contract – ввод понятия, предпосылки к появлению, рассмотрение возможности его реализации на базе OAS (Swagger);
- RAML + annotations + overlays как база для Single contract, примеры;
- Проблемы RAML, концептуальные разногласия разработчиков;
- Идея SaaS сервиса на базе вышеизложенной идеи (картинка прототипа сверху).
Система автоматического документирования REST-API в Laravel проектах
2018-05-14 в 9:10, admin, рубрики: laravel, php, swagger, документацияПреамбула
Для того, чтоб описать и задокументировать правила клиент-серверного
взаимодействия используя Rest-api можно выделить три основных метода:
- Описывать своим коллегам правила обращения к серверу на пальцах
Этот метод быстр и не требует долгосрочной поддержки, но высока вероятность, что вас за это будут бить.
- Руками составлять Google-docs/Wiki/Readme в проекте
Удобно тем, что однажды написанная документация не требует повторного объяснения. Её можно показать коллегам и даже иногда заказчику. Минусом данного метода является долгосрочная поддержка такой документации. Когда Api в проекте вырастает до таких размеров, что сама мысль "А когда же я обновлял документацию?" вызывает холодок по спине, тогда вы понимаете, что дальше так продолжаться не может. Формально вы можете обновлять документацию очень часто и маленькими фиксами, но это до первого отпуска. -
Использовать систему автодокументирования
И вот для того, чтобы решить минусы первых двух методов человечество придумало системы автоматического документирования. Основная идея заключается в том, что к проекту пристыковывается некий плагин, который собирает информацию по вашему коду, сам составляет документацию и обёртывает её в удобочитаемый формат. Но большинство решений по этому методу не идеальны. Давайте попробуем сделать инструмент, который поможет получить документацию нашего проекта с минимальным количеством телодвижений
Документирование API — документация из тестов
2018-03-21 в 4:55, admin, рубрики: rspec, swagger, документация, Программирование, тестирование, Тестирование веб-сервисовПост в продолжение темы экспериментальных решений (https://habrahabr.ru/post/350382/), откуда будет переиспользован код для примера. В прошлом посте я затронул тему, как можно написать тесты на простой сервис, когда он выступает в роли черного ящика и из кода теста у нас нет прямого доступа к коду тестируемой программы. Ещё раз остановлюсь на том, что тестируемый сервис был реализован на языке Go, а тесты к сервису на языке Ruby и фрэймворке для тестирования RSpec. Стэк был выбран из собственных предпочтений и не имеет ключевого значения к рассматриваемой теме. В этой статье хочу рассмотреть вопрос документирования API, вновь используя не совсем стандартное решение.
Читать полностью »
Готовим свой UI-интерфейс к Zabbix API средствами React component
2017-12-06 в 8:20, admin, рубрики: docker, gulp, nodejs, openapi, ReactJS, swagger, zabbix api, Разработка веб-сайтовВсем привет!
Все началось с интеграции телефонной платформы в корпоративный сайт.
Будучи инженером VoIP телефонии, WEB-разработка поразила разнообразием подходов и методов реализации. Стек технологий пестрит разнообразием, выбор инструментов определяет стиль разработки, модульность или закостенелость проекта.
Про телефонную платформу я напишу в следующий раз. Сильный уклон в VoIP-специфику отвлечет от главного — методов разработки современного SPA-приложения.
В статье будет описан процесс внедрения стороннего сервиса в существующую рабочую среду.
Сегодня поиграемся с Zabbix-API.
Новый API Яндекс.Кассы: платежное лего для e-commerce всех мастей
2017-10-17 в 7:55, admin, рубрики: api, swagger, yaml, Блог компании Яндекс.Деньги, платежные системы, Программирование, Разработка под e-commerce, яндекс.касса
Буквально сегодня свет увидел новый API Яндекс.Кассы, разработанный программистами для программистов. Набор протоколов стал единообразным, логичным и простым в освоении. Но статья не об этом – я хочу рассказать, как и почему в один прекрасный момент API решено было переписать с нуля.
Под катом вы найдете немного страданий перфекциониста, боли разработчиков и наш подход к применению лучших паттернов проектирования в специфическом финансовом продукте.Читать полностью »