Главная Блог Статьи Конференции Портфолио Flash-point RSS  RU EN

Владимир Бондаренко

Специалист по web-технологиям
ПОСЛЕДНИЕ ЗАПИСИ
  •  Тьма за спиной – мобильный квест написанный Виталием Зыковым
  •  Автоматизация процессов в компании: объединение всей информационной среды в одной системе Mauris CRM (CMS + SalesForce + MailChimp + мобильное приложение)
  •  10 советов по созданию страницы своей компании в «Википедии»
  •  Сравниваем форматы для документирования RESTful API: WADL, Swagger, I/O Docs, API BluePrint, RAML, Google API Discovery, Apimatic

  • ОБЛАКО ТЕГОВ
    Ajax Apple Chrome cloud CMS ECM Flash-point Folium iPad iPhone Java Script jQuery mobile development MVC PHP Python RESTful API SDK SEO StarCraft Swagger Twitter блоги видео кодирование конференция обучение SEO оцифровка информации плагины презентация программирование развлечение скрипт советы сравнение технологии хостинг ЧПУ
    КОНТАКТЫ

    Skype: coolweb_ua

    twitter

    СЧЕТЧИК


    Почему не стоит использовать Swagger как сервис для документирования RESTful API?

     

    Почему не стоит использовать Swagger как сервис для документирования RESTful API?

    На сегодняшний день открытый проект Swagger является флагманом в секторе генераторов автоматизированных SDK для документированных RESTful API. Также он занимает первые места в рейтинге популярных инструментов для документирования RESTful API. Я поверил статьям и решил испытать все возможности Swagger и, увы, пришел к неутешительному выводу…

    Самая большая проблема, с которой я столкнулся за время работы со Swagger, оказалась несовместимость версии формата документирования и генератора SDK. Сейчас редактор документации поддерживает только новый формат 2.0, а  генератор SDK только версии до 1.2. Вопрос: Как до выхода новой версии (уже в разработке 8 месяцев) пользоваться генератором SDK?

    В результате тестирования редактора документации Swagger 2.0 оказалось, что их формат значительно избыточное таких форматов как RAML, API Blueprint. Синтаксис требует создания особого формата для сложных структур запросов. Итог: формат Swagger 2.0 - избыточен и усложняет понимание исходного кода.

    Я решил воспользоваться документацией и написать простой пример без редактора. Зашел в документацию, просмотрел основные параметры и чуть ниже натолкнулся на надпись: “TODO: добавить примеры”. На этом этапе пропали все надежды на Swagger, как на универсальное решение для RESTful API и автоматизированных SDK.

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

    • http://restunited.com/ - (форматы: Postman, Alpaca, Swagger, 3Scale, I/0 Docs, API BluePrint);

    • https://apimatic.io/ - форматы: APIMATIC , WADL, Swagger, I/O Docs, API BluePrint, RAML, Google API Discovery, Mashape).

    Сейчас направление RESTful API активно развивается и регулярно появляются новые интересные решения. Например, REST United генерирует SDK с помощью Swagger, но благодаря автоматизации всей цепочки и большому количеству входных форматов - их сервис выглядит перспективнее.


    Теги:  Swagger, RESTful API, SDK

    Читать по теме:

     Сравниваем форматы для документирования RESTful API: WADL, Swagger, I/O Docs, API BluePrint, RAML, Google API Discovery, Apimatic
     Автоматическая генерация SDK для RESTful API
     Перечень сервисов для документирования RESTful API

    loading

    Написать комментарий

    Имя:
    Почта (скрыта):
    Сайт:
    Текст: :) :( 0_o =-0 =-D 8-) :-(( TT >:o ]:->

    Использование любых материалов сайта возможно только при размещении активной и прямой ссылки на VBond.Kiev.ua.

    Главная | Блог | Статьи | Конференции | Портфолио | Flash-point | RSS

    developed by Bondarenko Volodymyr