Pull to refresh
  • by relevance
  • by date
  • by rating

На пути к полной типизации с TypeScript, Swashbuckle и AutoRest

True Engineering corporate blog JavaScript *.NET *API *TypeScript *
Tutorial

Введение


В данной статье рассматривается вопрос о том, как реализовать обмен типизированными сообщениями между Back-End на основе ASP.NET Web API и Front-End, созданного с использованием TypeScript. Это приобретает особенное значение при работе над объёмными проектами, и тем-более важно, если команда является распределенной. Например, когда Back-End и Front-End разработчики работают из разных мест, в разных часовых поясах, и не всегда имеют возможность проконтактировать и обсудить что-либо. В этом случае отслеживание изменений представляет кропотливую работу, которая может быть чревата множеством трудноуловимых ошибок.

Для автора статьи, как для человека, который пришел к разработке Front-End со стороны WPF и Silverlight, большой проблемой, стало отсутствие статической типизации. Сколько раз вместо того чтобы сложить “2” и “2” складывал “2” и “Функцию возвращающую 2”, или передавал DOM объект вместо его jQuery обертки. Появление статических анализаторов кода, таких как JSLint, несколько облегчило проблему, но настоящим прорывом, особенно в командной разработке, для нас стал TypeScript.


Читать дальше →
Total votes 21: ↑19 and ↓2 +17
Views 13K
Comments 3

Оверинженеринг при документировании ViewSets Django REST Framework

Python *
Случается в нашей жизни, уважаемые коллеги, что хочешь сделать как проще, а получается как у новичка. И, что интересно, существует не мало мощных инструментов, которые предлагают простое решение в обмен на душу. Я имею ввиду, что цена абстракции бывает несоразмерна красоте её использования. Для меня примером такого неравноценного обмена стал Django Rest Framework 3.4.0, его механизм ViewSets и необходимость вывести подробную документацию по разрабатываемому API.

Читать дальше →
Total votes 13: ↑10 and ↓3 +7
Views 17K
Comments 16

Настройка Swashbuckle (Swagger) для WebAPI

Website development *.NET *Designing and refactoring *
Кто хоть раз тестировал свой WebAPI знает такие инструемнты, как Postman или Advanced REST (экстеншены для Chrome). Эти инструемнты всем удобны, кроме того, что не умеют сами узнавать какие модели принимает API, какие отдает и не предоставляет информацию обо всех возможных эндпоинтах. Это неудобство решает пакет Swashbuckle, который встраивает в проект генерацию Swagger спецификации и UI. Под катом коротко о том, как его прикрутить к проекту и некоторые детали относительно авторизации и работы с «перегруженными» эндпоинтами.
Читать дальше →
Total votes 12: ↑10 and ↓2 +8
Views 46K
Comments 11

Swagger в Magento 2

Development for e-commerce *

Тенденция перехода от сборки HTML-страниц на стороне сервера к их сборке на стороне клиента уже даже не тенденция, а тренд. Magento 2, шагая в ногу со временем в меру своих возможностей, также пытается быть в тренде, разнося обработку данных и их представление. Как простому разработчику заглянуть в "чистые" данные, если их представление вынесено достаточно далеко? Есть множество других хороших решений (начиная c tcpdump), и есть swagger.


image


Swagger достаточно хорошо интегрирован в Magento 2 (если только вам в голову не пришла дурацкая затея изменить код для "default" витрины). Все, что нужно для того, чтобы начать разглядывать "чистые" данные в Magento 2 с точки зрения удаленного приложения — использовать интегрированный в нее Swagger. В данном материале я не рассматриваю особенности использования самого Swagger'а, а просто привожу пример того, как использовать Swagger, интегрированный в Magneto 2, в режиме анонимного пользователя и в режиме аутентифицированного пользователя.

Читать дальше →
Total votes 15: ↑14 and ↓1 +13
Views 7.7K
Comments 0

Документирование #микросервисов

Web services testing *


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


Читать дальше →
Total votes 17: ↑14 and ↓3 +11
Views 98K
Comments 13

ASP.NET Core: Создание справочных страниц веб-API ASP.NET с помощью Swagger

Microsoft corporate blog Open source *.NET *ASP *C# *
Translation
Tutorial
При создании высоконагруженных приложений бывает сложно разобраться в различных API. Сформировать качественную документацию и справочные страницы в рамках веб-API посредством Swagger с интеграцией Swashbuckle .NET Core так же просто, как добавить пару пакетов NuGet и изменить Startup.cs.


Читать дальше →
Total votes 24: ↑23 and ↓1 +22
Views 33K
Comments 2

Свой велосипед для JSON API

SuperJob corporate blog PHP *Programming *API *
Всем привет! На недавно прошедшем Superjob IT Meetup я рассказывал о том, как мы в Superjob разрабатываем свой API для проекта с миллионной аудиторией и кучей различных платформ.

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

Читать дальше →
Total votes 13: ↑12 and ↓1 +11
Views 10K
Comments 40

Декларативное программирование в web-е

Website development *PHP *Programming *XML *API *

image


Что же такое декларативное программирование? Википедия подскажет нам:


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

Далее в статье пойдет речь о том, как использовать данную парадигму в современном web-программировании. В частности, я хотел бы затронуть вопрос о валидации/верификации входных данных для веб сервисов. Примеры будут на php, так как это язык мне наиболее близок в профессиональном плане.

Читать дальше →
Total votes 19: ↑17 and ↓2 +15
Views 22K
Comments 12

Как перейти на gRPC, сохранив REST

Programming *API *Go *Development of communication systems *
Tutorial

Многие знакомы с gRPC — открытым RPC-фреймворком от Google, который поддерживает 10 языков и активно используется внутри Google, Netflix, Kubernetes, Docker и многими другими. Если вы пишете микросервисы, gRPC предоставляет массу преимуществ перед традиционным подходом REST+JSON, но на существующих проектах часто переход не так просто осуществить из-за наличия уже использующихся REST-клиентов, которые невозможно обновить за раз. Нередко общаясь на тему gRPC можно услышать "да, мы у нас в компании тоже смотрим на gRPC, но всё никак не попробуем".


Что ж, этой проблеме есть хорошее решение под названием grpc-rest-gateway, которое занимается именно этим — автогенерацией REST-gRPC прокси с поддержкой всех основных преимуществ gRPC плюс поддержка Swagger. В этой статье я покажу на примере как это выглядит и работает, и, надеюсь, это поможет и вам перейти на gRPC, не теряя существующие REST-клиенты.


Читать дальше →
Total votes 12: ↑10 and ↓2 +8
Views 75K
Comments 16

Новый API Яндекс.Кассы: платежное лего для e-commerce всех мастей

ЮMoney corporate blog Payment systems *Programming *API *Development for e-commerce *


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


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

Читать дальше →
Total votes 17: ↑17 and ↓0 +17
Views 21K
Comments 26

Готовим свой UI-интерфейс к Zabbix API средствами React component

Website development *
Sandbox
Всем привет! Все началось с интеграции телефонной платформы в корпоративный сайт.

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

Про телефонную платформу я напишу в следующий раз. Сильный уклон в VoIP-специфику отвлечет от главного — методов разработки современного SPA-приложения.

В статье будет описан процесс внедрения стороннего сервиса в существующую рабочую среду.

Сегодня поиграемся с Zabbix-API.

image
Читать дальше →
Total votes 9: ↑7 and ↓2 +5
Views 6.6K
Comments 4

Как за 10 минут сделать клиент к HTTP API на Swagger

Voximplant corporate blog Website development *Programming *Development of mobile applications *API *
Tutorial

Когда нужно сделать несколько запросов к HTTP API, разработчик обычно берет свой привычный язык/фреймворк и быстро пишет аналог curl в коде: HTTP-запрос, минимальный контроль ошибок, query- или json-аргументы, парсинг json body с названиями полей в виде строк. Все это замечательно работает, пока проект не начинает расти и несколько вызовов не превращаются в несколько десятков, а куски низкоуровневого кода не начинают размножаться копипастой. А дальше — стандартный набор багов, рожденных копипастой, которые начинают понемногу есть время у разработчика.

Swagger/OpenAPI — один из «комбайнов» для работы с HTTP API. Это язык описания API (недавно произошло объединение проектов генератора и спеки), генераторы серверного и клиентского кода, документации, тестов — много всяких полезных штук. Под катом я покажу, как по «человеческому» описанию API на сайте компании в несколько строк кода составить OpenAPI-описание и сгенерировать клиент на Python. И чем такой клиент будет лучше, чем вручную написанный код.
Total votes 34: ↑32 and ↓2 +30
Views 67K
Comments 4

Как построить REST-like API в крупном проекте

ЮMoney corporate blog Programming *Designing and refactoring *API *Development for e-commerce *


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


Ключевые слова для оценки полезности: API, REST, OpenAPI, Swagger, рефакторинг взаимодействия систем.

Читать дальше →
Total votes 28: ↑26 and ↓2 +24
Views 39K
Comments 64

«Профит велик. Мы получили множество свобод, которыми не обладали раньше», — Владимир Плизга о микросервисах

JUG Ru Group corporate blog Java *

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


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


В свою очередь, Владимир Плизга последние 6 лет погружен в разработку бэкенда интернет-банков и сопутствующих сервисов в ЦФТ, где активно топит за микросервисы и прочие модные штуки. Чтобы пообщаться с ним, я приехал прямо в офис ЦФТ, сделал сэлфи и обязательную фотку красного слона :-)


Обсуждаемые темы:


  • Зачем нужны микросервисы;
  • Как с ними жить (судьба REST и SOAP, statefull vs. stateless, переход от монолита к микросервисам, совместимость с legacy и многое другое);
  • Микросервисные технологии (Spring Cloud Netflix, Zuul, ...), какие с ними проблемы, что нужно допиливать;
  • Документация: на русском или английском? Написание и генерация документации (Swagger, SpringMVC, SpringFox). Архитектурные диаграммы — нужны ли, в чем рисовать, как хранить;
  • Мониторинг, восстановление от сбоев;
  • Ну и самое главное: стоит ли игра свеч?


(слева — Владимир, справа — olegchir)

Читать дальше →
Total votes 29: ↑28 and ↓1 +27
Views 12K
Comments 0

Документирование API — документация из тестов

Programming *Web services testing *
Пост в продолжение темы экспериментальных решений, откуда будет переиспользован код для примера. В прошлом посте я затронул тему, как можно написать тесты на простой сервис, когда он выступает в роли черного ящика и из кода теста у нас нет прямого доступа к коду тестируемой программы. Ещё раз остановлюсь на том, что тестируемый сервис был реализован на языке Go, а тесты к сервису на языке Ruby и фрэймворке для тестирования RSpec. Стэк был выбран из собственных предпочтений и не имеет ключевого значения к рассматриваемой теме. В этой статье хочу рассмотреть вопрос документирования API, вновь используя не совсем стандартное решение.
Читать дальше →
Total votes 11: ↑10 and ↓1 +9
Views 14K
Comments 0

Система автоматического документирования REST-API в Laravel проектах

PHP *Laravel *
Sandbox

Преамбула


Для того, чтоб описать и задокументировать правила клиент-серверного
взаимодействия используя Rest-api можно выделить три основных метода:


  1. Описывать своим коллегам правила обращения к серверу на пальцах
    Этот метод быстр и не требует долгосрочной поддержки, но высока вероятность, что вас за это будут бить.
  2. Руками составлять Google-docs/Wiki/Readme в проекте
    Удобно тем, что однажды написанная документация не требует повторного объяснения. Её можно показать коллегам и даже иногда заказчику. Минусом данного метода является долгосрочная поддержка такой документации. Когда Api в проекте вырастает до таких размеров, что сама мысль "А когда же я обновлял документацию?" вызывает холодок по спине, тогда вы понимаете, что дальше так продолжаться не может. Формально вы можете обновлять документацию очень часто и маленькими фиксами, но это до первого отпуска.
  3. Использовать систему автодокументирования
    И вот для того, чтобы решить минусы первых двух методов человечество придумало системы автоматического документирования. Основная идея заключается в том, что к проекту пристыковывается некий плагин, который собирает информацию по вашему коду, сам составляет документацию и обёртывает её в удобочитаемый формат. Но большинство решений по этому методу не идеальны. Давайте попробуем сделать инструмент, который поможет получить документацию нашего проекта с минимальным количеством телодвижений

Читать дальше →
Total votes 14: ↑14 and ↓0 +14
Views 19K
Comments 6

Начало работы с микросервисами в Spring Boot

OTUS corporate blog API *Microservices *
Всем привет!

В этой статье мы продемонстрируем основные компоненты для создания RESTful микросервисов, используя реестр служб Consul, Spring Boot для всего скаффолдинга, инжекции зависимостей, Maven для сборки, а также Spring REST и Jersey/JaxRS API Java RESTful.

Основные преимущества микросервисов:

  • Микросервисы позволяют ослабить зацепленность вашего кода

  • Микросервисы позволяют различным командам работать над небольшими составляющими, используя независимые технологии, обеспечивая более безопасное и частое развертывание Spring Boot поддерживает различные реализации для создания REST API

  • Обнаружение и вызов сервисов не зависят от сервисной платформы

  • Swagger создает надежную документацию API и интерфейс вызова

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

Total votes 10: ↑7 and ↓3 +4
Views 20K
Comments 6

От API first на Swagger до Single contract на RAML

Website development *Open source *Programming *System Analysis and Design *API *
Sandbox
image

Привет, %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 сервиса на базе вышеизложенной идеи (картинка прототипа сверху).


Читать дальше →
Total votes 9: ↑9 and ↓0 +9
Views 10K
Comments 2

Предбольничный хотфикс или “Эй, Swagger! А где мои ошибки”?

Abnormal programming *Java *Designing and refactoring *
Случалось ли вам налажать во время хотфикса в мастер? Нет?! А вот мне удалось!

Эта история о том, как я забыл обновить документацию. Как в итоге, написал плагин для Swagger (со второго раза). И как увлекся этим так, что забыл про свой больничный и пошел на поправку!


А еще немного про Optional не из Java 8.
История провала и успеха
Total votes 11: ↑9 and ↓2 +7
Views 3K
Comments 0

5+1 случай, когда спецификация REST API играет огромную роль

PHP *JavaScript *Ruby on Rails *Node.JS *API *
Translation
Tutorial

В этой статье речь пойдёт о написании и поддержке полезной и актуальной спецификации для REST API-проекта, которая позволит сэкономить много лишнего кода, а также серьёзно улучшить целостность, надежность и прозрачность прокта в целом.


Что такое RESTful API?



Это миф.


Серьёзно, если вы думаете, что в вашем проекте RESTful API, вы почти наверняка ошибаетесь. Идея RESTful — в построении API, который во всём соответствовал бы архитектурным правилам и ограничениям, описанным стилем REST, однако в реальных условиях это оказывается почти невозможно.

Читать дальше →
Total votes 35: ↑34 and ↓1 +33
Views 28K
Comments 32