Сергей Огородников «A proper way to develop a REST service»

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

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

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

Transcript

1. A proper way to develop a REST service Sergey Ogorodnikov Senior C# developer One Inc Omsk, 4/18/2019
2. 2 Use Swagger, Luke! Swagger is an open-source software framework backed by a large ecosystem of tools that helps developers design, build, document, and consume RESTful Web services. While most users identify Swagger by the Swagger UI tool, the Swagger toolset includes support for automated documentation, code generation, and test-case generation. https://swagger.io/
3. The OpenAPI Specification The OpenAPI Specification defines a standard, programming language- agnostic interface description for REST APIs, which allows both humans and computers to discover and understand the capabilities of a service https://www.openapis.org 3
4. Swashbuckle 4
5. ProcessOne API Specification 5
6. ProcessOne API Specification 6
7. Swagger-UI 7
8. Swagger-codegen 8 Supported languages (with code and mustache templates): • Java (client, service, JMeter, different http libraries, frameworks), Scala, Kotlin • CSharp (dotnet2, dotnet4, .Net Core, client, controller) • Typescript (angualr, angularjs, fetch, aurelia, jquery, node...) • python, php, ruby/groovy, rust, r, perl, go… • ada, eiffel… • confluence/wiki https://docs.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle
9. Swagger-codegen + crutch 9 A script to generate client libraries with our custom swagger- codegen: Our custom swagger-codegen with a little crutch:
10. ProcessOne Java SDK 10
11. Made by Microsoft, distributed as NPM package, runs on Node.js Supports languages (with extension packages): • CSharp both client and service (generated code uses Microsoft.Rest.ClientRuntime package; supports .Net standart) • Typescript • Java • Python Autorest 11
12. The project combines the functionality of Swashbuckle (Swagger generation) and AutoRest (client generation) in one toolchain. This way a lot of incompatibilites can be avoided and features which are not well described by the Swagger specification or JSON Schema are better supported (e.g. inheritance, enum and reference handling). NSwag 12
13. Generate client for frontend 13 *.tst template file should be added to solution:
14. Generate client for frontend 14 Our custom utility • creates typescript client using just compiled assembly metadata • may work as standalone tool • is a part of build process
15. Go futher 15 Each microservice may use its own client + will implement only needed methods + decoupling + no need to write client foreach service - should write more code Use HATEOAS/HAL - let REST be self-descriptive in runtime + decoupling + independent from paths - difficult to implement
16. Questions? Thanks! 16