Swagger & OpenAPI Spec #openapi

Muhammad Siddiqi

@SiddiqiMuhammad

alternatestack.comshujaat.net

About me…???

http://alternatestack.com/

http://shujaat.net/

@SiddiqiMuhammad

AgendaAPI Economy

Issues with APIs

Swagger’s Introduction & History

Details about Swagger Spec

Degree of RESTfulness

Approaches for Swaggerizing

Swagger Alternatives

@SiddiqiMuhammad

Why so much interest in API Design?

code camps - # Sessions discussing API Design & Dev

What’s driving API Boom?

By 2019, more than 30 percent of the 100 largest vendors' new software investments will have shifted from cloud-first to cloud-only. Gartner - Jun’16

The worldwide Internet of Things market is predicted to grow to $1.7 trillion by 2020, marking a compound annual growth rate of 16.9%. IDC Worldwide Internet of Things Forecast, 2015 – 2020.

An estimated 25 billion connected “things” will be in use by 2020. – Gartner Newsroom

API Economy

@SiddiqiMuhammad

Muhammad Siddiqi

Uber is a platform built on APIs provided by e.g. Google Maps.So these APIs create value chains.It’s just a matter of claiming your share.The API economy is an enabler for turning a business or organization into a platform.Semantic web is only possible with APIs working together to fulfill client’s needs.We live in an API economy, a set of business models and channels based on secure access of functionality and exchange of data.

deux problèmes

مسائل دو

mavuto awiriבעיות שתי

兩個問題

Due problemi

مشكلتين

iki sorun

abụọ nsogbu

రెండు సమస్యలు

dua masalah

مشکل دو

Две проблемы

Dos problemas

Two problems

@SiddiqiMuhammad

Pain for developers

Using an REST API

As a consumer

As a provider

Available UrisParameters?Payloads

Supporting user is hardMaintaining API documentation is difficult

@SiddiqiMuhammad

Distributed MonolithBen Christensen

models lib models lib

The Platform Libraries required to run services / Libraries to interact with services

“The evils of too much coupling between services are far worse than the problems caused by code duplication”Sam Newman(Building Microservices)

Central Authority Technical evolution of teams

Polyglot Development Not possible

When a service cannot interact within a system unless all these libraries are available.

Per Conway’s Law, affects design

Extreme Programming DRY Principle Overdoing can result in Distributed Monolith

string jsonResponse = @"{ 'Name': 'Bad Boys', 'ReleaseDate': '1995-4-7T00:00:00', 'Genres': [ 'Action', 'Comedy' ]}";

Movie m = JsonConvert.DeserializeObject<Movie>(json);

How to solve this??

leverage contracts and protocols

@SiddiqiMuhammad

Swagger

- Defines Interface to REST API

- Language agnostic

- API Specs / API Docs —-> JSON / YAML format

- No guesswork in calling the service

- Contract for REST Service

OpenAPI

SpecSwagger

Eco-system

- Documenting RESTful APIs

- Open sourced

@SiddiqiMuhammad

Muhammad Siddiqi

Makes consumption of your API easier by providing details about everything need to use your api. (methods, resources, parameters, media types)API adoption is affected by proper documentationThis includes both private (in your enterprise) or public APIs.

It has been there for a while…

wordnik —-> SmartBear

Open API Initiative -> working group under Linux foundation

Swagger 2.0 is Open API Spec… Next version -> de-swaggered and would be called OAS 3.0

@SiddiqiMuhammad

Many good people are behind it?

Muhammad Siddiqi

There are members which have one member in board of directors.There is also a technical committee, which you can be a part of.

Muhammad Siddiqi

What’s changed in 2.0?https://github.com/OAI/OpenAPI-Specification/wiki/Swagger-1.2-to-2.0-Migration-Guidemodels changed to schemasResources removed. Operations are now described with paths.Multiple files changed to single file.only one base path allowed. Earlier versions allowed different base paths on operations level.

swagger.ioOpen APIopenapis.org

@SiddiqiMuhammad

http://swagger.io/

http://openapis.org/

Discussion about Spec

Metadata about API (name, description, host, basepath, …)

ResourcesParametersResponsesUnderlying Data ModelSecurity

@SiddiqiMuhammad




@SiddiqiMuhammad




@SiddiqiMuhammad

Swagger Structure - Data Types

@SiddiqiMuhammad

- - - -- - - -- - - -

API Spec

Service Code

Client code

Swagger tools

Contract First

- - - -- - - -- - - -

API Spec

Client code

Swagger tools

Code First

Service(Swagger-helper api)

Approaches for Swagger-izing APIs

ClientServer

http

@SiddiqiMuhammad

Muhammad Siddiqi

Code First: Code annotations, comments, embedded documentationNo need to maintain separate specSpec is always updatedDesign First:Here spec is the single truth about your apiSpec is implementation guidelineSpec is outside your codeOne apparent problem: what if somebody goes to the server code after generation and changes it. Well, if that happens then screw him, the clients would still be using the spec, so they might be broken. So the change would be immediately noticed. so you are fine.

Muhammad Siddiqi

Approaches based on Provider and Consumer (Jerome Louver - Chief Geek at Restlet)code first & provider drivencontract first and provider drivencollaborative contract first contract first and consumer drivencontract first and consumer owned ???

Swagger Community

Google Group

IRC Channel : #swagger

Twitter

http://apiawards.co/

@SiddiqiMuhammad

Is my API RESTful?

Can this be answered as Yes / No?

Are there degree of RESTfulness?

April

0 20 40 60 80 100

Level 0: Swamp of POX

Level 1: Resources

Level 2: HTTP Verbs

Level 3: HATEOAS

Richardson’s Maturity Model

Swagger 2.0

OpenAPI.next

@SiddiqiMuhammad

Swagger.Ed

Graphical Representation of API

chrome extension @chefarchitect

@SiddiqiMuhammad

Muhammad Siddiqi

@chefarchitect: Chris Spiliotopoulos

OpenAPI.next

Breaking change… :(

Hypermedia support

Extended JSON Schema support… any of, not operators

Callback style events / non request / response drivenHTTP 2.0 and socket techniques

WebHooksServer could tell what sort of signatures are needed. Consumer sending message back. [subscription, un-subscription, retry]

@SiddiqiMuhammad

OpenApi.Next (3.0)openapis.org

@SiddiqiMuhammad

http://openapis.org/

Service First / Code First

scalatra-swagger"com.wordnik" %% "swagger-play2"

ASP.Net Web API —- > Swashbuckle

Automated API Spec Generation?

swagger-node-express

SpringFox -> Automated JSON API documentation for API's built with Spring

@SiddiqiMuhammad

http://asp.net/

Muhammad Siddiqi

Show the API spec generated from Swashbuckle in ASP.Net

Spec First / Contract FirstSwagger.io Editor Restlet

SwaggerHub

@SiddiqiMuhammad

Muhammad Siddiqi

Create Test API with Restlet

Muhammad Siddiqi

Use StudentAPI and show client and server code generation

Muhammad Siddiqi

Show export to API Gateway

Muhammad Siddiqi

Dredd API Tester

Validating Swagger Spec

Swagger Validator Badge

<img src="http://online.swagger.io/validator?url={YOUR_URL}">

@SiddiqiMuhammad

Muhammad Siddiqi

swagger validate https://api.apis.guru/v2/specs/nytimes.com/top_stories/2.0.0/swagger.json

Client Code GenerationAPI Operations

Model Classes

AutorestNSwagswagger-codegeneditor.swagger.ioRestletAPIMATIC

@SiddiqiMuhammad

swagger-codegen generate -l html -i https://api.apis.guru/v2/specs/bitbucket.org/2.0/swagger.json

Muhammad Siddiqi

Use swagger-codegen to generate java code for the APIapi docs (/Users/muhammadsiddiqi/Desktop/nyc/approaches/schema-first/swagger-codegen)- swagger-codegen generate -l dynamic-html -i https://api.apis.guru/v2/specs/bitbucket.org/2.0/swagger.jsonnpm installnode .(runs on 8002 [in main.js] - http://localhost:8002)(uses express)HTMLswagger-codegen generate -l html -i https://api.apis.guru/v2/specs/bitbucket.org/2.0/swagger.json

Documentation for Developers

swagger-ui

swagger-codegen

asciidoctor?? — Swagger2Markup

@SiddiqiMuhammad

Dynamic Client Code GenerationSwaggerProvider: F# type providerSergey Tihon

Javascript

Python

@SiddiqiMuhammad

Muhammad Siddiqi

SwaggerProvider nuget packageSergey Tihon

Where to find API Specs

@SiddiqiMuhammad

Muhammad Siddiqi

API Specs can be available by the API providers themselves. Then they have a responsibility to versioning and maintenance of the specs. https://watson-api-explorer.mybluemix.net/Is there a public space available for API specs as we have package managers including nuget.org or npm / bower?Nothing official yet but APIs.GURU and API Stack are closer.

Swagger and Postman

Postman collections can be generated

@SiddiqiMuhammad

Muhammad Siddiqi

Many developers have started using Postman as part of their API workflow. This can be added as part of the build workflow using its newman tool.We can generate postman collections by importing swagger spec directly from a URL.Once you create collections, you can share it with your team. You can keep a sample response with the collection and compare it with a future response.And so on…

Swagger Alternatives

@SiddiqiMuhammad

Thank You!

@SiddiqiMuhammad

@SiddiqiMuhammad

Software

Swagger & OpenAPI Spec #openapi