Swagger – умная документация вашего RESTful web-API — обзор Junior back-end developer-а для новичков



Предисловие


Команда, в которой я сделала свои первые шаги на поприще написания промышленного кода, занималась разработкой удобного API к функциональности программного продукта на C# (для удобства назовем его, скажем, буквой E), существовавшего уже много лет и зарекомендовавшего себя на рынке с весьма положительной стороны. И здесь вроде бы у юного падавана пока не должно возникать вопросов, однако же представим себе, что ранее вы, скорей всего, конечно, писали собственные web-API, но вряд ли для широкой аудитории, а значит жили по принципу «Сам создал – сам пользуюсь», и если вдруг кого-то бы заинтересовала функциональность вашего API, то вы, наверное, кинули бы ему pdf-файл с подробной инструкцией (по крайней мере я бы сделала именно так). «Где посмотреть функционал апи» — спросила я тимлида ожидая получить ссылку на текстовый документ. «Загляни в Swagger» — ответил он.

Постой, как так получается, что продукт успешно функционирует уже давно, а API вы к нему пишете только сейчас?


Все верно, как такового удобного публичного API у E до недавнего времени не существовало. Фактически вся работа происходила через web-интерфейс, а back-end состоял из множества внутренних микросервисов, с которыми невозможно было интегрироваться извне без четкого понимания внутренней бизнес-логики, уж не говоря о том, что сами они на значительную долю состояли из легаси. Нужно было обратить внимание на клиентов, которые хотят непосредственно напрямую взаимодействовать с сервером, а значит предоставить им красивое и удобное API. Что для этого потребуется? Все, о чем было написано чуть раньше – самим взять и наладить работу со всеми внутренними микросервисами, а также обеспечить удобную и красивую документацию, сделав это красиво, понятно, и самое главное – коммерчески успешно.

Хорошо, так что же есть такое Swagger и в чем его полезность миру?


По сути Swagger – это фреймворк для спецификации RESTful API. Его прелесть заключается в том, что он дает возможность не только интерактивно просматривать спецификацию, но и отправлять запросы – так называемый Swagger UI, вот так это выглядит:



Как мы видим – полное описание методов, включая модели, коды ответов, параметры запроса – в общем, наглядно.

И как это работает?


Отличное руководство для внедрения Swagger в ASP.NET Core
с нуля есть вот в этой этой статье.

Идея в конфигурации отображения с помощью специальных аннотаций у методов API, вот пример:





Swagger Codegen




Если очень хочется, то можно сгенерировать непосредственно клиента или сервер по спецификации API Swagger, для этого нужен генератор кода Swagger-Codegen. Описание из документации, думаю, пояснять не требуется:
This is the Swagger Codegen project, which allows generation of API client libraries (SDK generation), server stubs and documentation automatically given an OpenAPI Spec. Currently, the following languages/frameworks are supported:

  • API clients: ActionScript, Ada, Apex, Bash, C# (.net 2.0, 3.5 or later), C++ (cpprest, Qt5, Tizen), Clojure, Dart, Elixir, Elm, Eiffel, Erlang, Go, Groovy, Haskell (http-client, Servant), Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Google API Client Library for Java, Rest-assured), Kotlin, Lua, Node.js (ES5, ES6, AngularJS with Google Closure Compiler annotations) Objective-C, Perl, PHP, PowerShell, Python, R, Ruby, Rust (rust, rust-server), Scala (akka, http4s, swagger-async-httpclient), Swift (2.x, 3.x, 4.x), Typescript (Angular1.x, Angular2.x, Fetch, jQuery, Node)
  • Server stubs: Ada, C# (ASP.NET Core, NancyFx), C++ (Pistache, Restbed), Erlang, Go, Haskell (Servant), Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy, Play Framework, PKMST), Kotlin, PHP (Lumen, Slim, Silex, Symfony, Zend Expressive), Python (Flask), NodeJS, Ruby (Sinatra, Rails5), Rust (rust-server), Scala (Finch, Lagom, Scalatra)
  • API documentation generators: HTML, Confluence Wiki
  • Configuration files: Apache2
  • Others: JMeter
Прочая информация, в частности инструкция по использованию, представлена здесь:
Общая информация

И здесь: Подробная информация

Заключение


Это был краткий наглядный обзор для начинающих разработчиков API, целью которого было предоставить общую картину того, что такое Swagger, зачем он нужен и какие он дает основные плюсы с моей личной точки зрения.
  • +8
  • 9,5k
  • 7
Поделиться публикацией

Комментарии 7

    0
    Почему swagger, а не его приемник OpenAPI?
    +4
    >Это был краткий наглядный обзор для начинающих разработчиков API
    Суперкраткий
      0
      Краткость сестра таланта!
      0
      Использую Nswag. В последней версии UI какой-то страшный сделали, старый, который на скринах, намного удобнее.
        0
        Команда, в которой я сделал свои первые шаги на поприще написания промышленного кода, разрабатывает, о ужас! апи набирая код, а получившееся описывет в гуглодоках. Клиент вроде как доволен, хотя обратная связь только через лида и в гуглодоке клиенту разрешены только комменты :)
          0
          Так и не смог заставить себя полюбить описывать сервисы в Свагере. Конечно, приходится им пользоваться как «индустриальным стандартом», но как-то неприятно это делать. От многих архитекторов слышал схожую брезгливость при работе со сваггером и его “замечательным” swagger-editor.

          Очень рекомендую присмотреться к RAML-у. Тулинг вокруг него конечно сильно меньше, но вполне достаточно для описания сервисов, а вот синтаксис прямо в разы более «человеческий». В pet projects уже около года на него перешёл, а вот с командами сложнее, баззворды и «свагерогенераторы» по комментариям/аннотациями и пр. всегда побеждают.

          Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

          Самое читаемое