Everybody loves Swagger

transcript

Sponsored & Brought to you by

Massimo Crippa

https://twitter.com/mas_que_crippa

https://be.linkedin.com/in/massimocrippa

Nice to meet youMassimo Crippa

Integration Architect at Codit BizTalk D/I Api Management

massimo.crippa@codit.eucodit.eu/blog@mas_que_crippalinkedin.com/in/massimocrippa

AgendaIntroduction

The Swagger project

Integrations

Why APIs are trending➔ Open Innovation and New

Markets. Enable firms to use internal as well as external ideas and find new market paths

➔ Consume, Switch or Upgrade Seamlessly. Drive both the API Consumer and Provider towards a continuous improvement of quality

➔ Build on Partner Capabilities➔ Increase Brand Presence

➔ Generate New Revenue Streams

➔ Enable Composite Enterprise Approach where business functionalities become small configurable blocks.

➔ Reduce time-to-market➔ Fueled by mobile, cloud, big

data & IoT

The successful API➔ Easy to consume (TTFSC, TTFHW)➔ Understand the use, prevent the misuse (Data formats,

authentication, error codes)➔ Upgrade seamlessly➔ Getting started, Multi language code samples, SDKs (DevEx)

The documentation is CRUCIAL

What is Swagger?

Edit the API specification in YAML to produce the JSON

Editor

Layout, describe and document your API

Specification

A dependency-free collection of HTML / JS / CSS that consumes the swagger.json

Consume the swagger.json to create client and server code

Code-Gen

The specificationDefinition language to describe and document RESTful API➔ Metadata

➔ info, basepath, consumes, produces, etc..➔ Controllers (paths)

➔ Operations, HTTP verbs, status codes, schema refs➔ Objects Definition (definitions)

➔ Parameters (e.g. skip)➔ Responses➔ Security (e.g. oauth)

The editorsAPI Specification-First➔ Swagger Editor

➔ editor.swagger.io➔ Editor + swagger.js

➔ apistudio.io➔ Restlet studio (cross-format editor)

➔ studio.restlet.com

The Swagger UI It’s a dependency-free collection of HTML / JavaScript / CSS➔ List of APIs

➔ description, version, base path➔ Drill-down to the operations

➔ http methods➔ Description, Parameters, Types➔ Try-out the API

Community-driven toolsWhole world of open source tools out there!

Swashbuckle.NET library to auto-generate the swagger.json➔ ApiExplorer to keep implementation and documentation in-

sync➔ Auto-generate as much as possible + extensibility points

➔ Discoverable (one endpoint per version)➔ Minimal impact to your API

➔ Shashbuckle.core➔ Shashbuckle

➔ Version 5.2.1➔ vNext 6.0.0 beta7

Integrations

API Management

API ManagementAzure API Management service➔ Produces swagger 2.0➔ Consumes 1.2 and 2.0

Sentinet by Nevatech➔ Introduced with the version 4.6 (October 2015)➔ Produces swagger 2.0➔ Consumes 2.0

Takeaways➔ A good developer experience is crucial to build a successful

API➔ Swagger is the de facto standard to describe modern APIs➔ Swashbuckle: discoverable swagger.json + UI for devs➔ Large number of applications and services that consume

swagger

References➔ Swagger

http://swagger.io/➔ Swashbuckle

https://github.com/domaindrivendev/Swashbuckle/➔ Microsoft Azure API Management

http://azure.microsoft.com/en-us/services/api-management/➔ Sentinet by Nevatech

http://www.nevatech.com/

Thank you!

Everybody loves Swagger

Technology