Introduction to Swagger

Introduction to Swagger
15.03.16 / Web API Meetup / Wer liefert Was?
@NilsLoewe

View Slide

What is Swagger?

View Slide

Swagger is a representation for REST APIs:
Interactive documentation
Client SDK generation
Discoverability
Supporting many programming languages and
environments
100% Open Source

View Slide

What's Open Source in this case?

View Slide

2011-08-10: First release of the Swagger Speci cation
To bring the “good parts” of REST, SOAP, Web Services and
RPC into a simple, easy to understand format.

View Slide

2014-09-08: Release of Swagger 2.0
Swagger tools are downloaded close to 15,000 times per day.
2000 known open-source repositories for Swagger tools
First-class support across all major API management
platforms.

View Slide

2016-01-01 The Open API Initiative
Part of the Linux Foundation
Founding partners: Google, Microsoft, IBM, 3Scale, Apigee,
CapitalOne, Intuit, PayPal, and Restlet.
openapis.org

View Slide

View Slide

How to use Swagger?

View Slide

New API: Top-Down
Use the Swagger Editor to create your Swagger de nition
Use the Swagger Codegen tools to generate server
implementation

View Slide

Existing API: Bottom-Up
You have an existing REST API
You want to create a Swagger de nition
Option A: Create the de nition manually using the
Swagger Editor
Option B: Integrate the framework into your Code and get
the Swagger de nition generated automatically

View Slide

Build a new client for a Swagger-described API
Use the online version of the Swagger UI to explore the API
(given that you have a URL to the APIs Swagger de nition)
Use Swagger Codegen to generate the client library

View Slide

Swagger Tools

View Slide

Swagger-Codegen
Generating client libraries and server stubs from a Swagger
de nition
Required: Java 7, Apache maven > 3.0.3
Available via homebrew, Docker, Vagrant, ...
https://github.com/swagger-api/swagger-codegen

View Slide

Swagger-UI
A dependency-free collection of HTML, Javascript, and CSS assets
that dynamically generate beautiful documentation and sandbox
from a Swagger-compliant API
Works in all common browsers (Chrome, Safari, Firefox,
IE8++)
Download from https://github.com/swagger-api/swagger-
ui

View Slide

Available Integrations
Open Source Implementations available for
Clojure, Coldfusion, D, Eiffel, Erlang, Go, Groovy, Haskell,
Java, Javascript, TypeScript, .NET, Node.JS, Perl, Python, Php,
Ruby, Scala
Commercial Implementations available for
http://swagger.io/commercial-tools/

View Slide

Describing APIs with Swagger

View Slide

A 'hello world' API
s
w
a
g
g
e
r
: "
2
.
0
"
i
n
f
o
:
v
e
r
s
i
o
n
: "
1
.
0
"
t
i
t
l
e
: "
H
e
l
l
o W
o
r
l
d A
P
I
"
p
a
t
h
s
:
/
h
e
l
l
o
/
{
u
s
e
r
}
:
g
e
t
:
d
e
s
c
r
i
p
t
i
o
n
: R
e
t
u
r
n
s a g
r
e
e
t
i
n
g t
o t
h
e u
s
e
r
!
p
a
r
a
m
e
t
e
r
s
:
n
a
m
e
: u
s
e
r
i
n
: p
a
t
h
t
y
p
e
: s
t
r
i
n
g
r
e
q
u
i
r
e
d
: t
r
u
e
d
e
s
c
r
i
p
t
i
o
n
: T
h
e n
a
m
e o
f t
h
e u
s
e
r t
o g
r
e
e
t
.
r
e
s
p
o
n
s
e
s
:
2
0
0
:
d
e
s
c
r
i
p
t
i
o
n
: R
e
t
u
r
n
s t
h
e g
r
e
e
t
i
n
g
.
s
c
h
e
m
a
:

View Slide

API Info
t
i
t
l
e s
t
r
i
n
g R
e
q
u
i
r
e
d
. T
h
e t
i
t
l
e o
f t
h
e a
p
p
l
i
c
a
t
i
o
n
.
d
e
s
c
r
i
p
t
i
o
n s
t
r
i
n
g A s
h
o
r
t d
e
s
c
r
i
p
t
i
o
n o
f t
h
e a
p
p
l
i
c
a
t
i
o
n
.
t
e
r
m
s
O
f
S
e
r
v
i
c
e s
t
r
i
n
g T
h
e T
e
r
m
s o
f S
e
r
v
i
c
e f
o
r t
h
e A
P
I
.
c
o
n
t
a
c
t O
b
j
e
c
t T
h
e c
o
n
t
a
c
t i
n
f
o
r
m
a
t
i
o
n f
o
r t
h
e e
x
p
o
s
e
d A
P
I
.
l
i
c
e
n
s
e O
b
j
e
c
t T
h
e l
i
c
e
n
s
e i
n
f
o
r
m
a
t
i
o
n f
o
r t
h
e e
x
p
o
s
e
d A
P
I
.
v
e
r
s
i
o
n s
t
r
i
n
g R
e
q
u
i
r
e
d P
r
o
v
i
d
e
s t
h
e v
e
r
s
i
o
n o
f t
h
e a
p
p
l
i
c
a
t
i
o
n A
P
I

View Slide

Data types
i
n
t
e
g
e
r i
n
t
e
g
e
r i
n
t
3
2 s
i
g
n
e
d 3
2 b
i
t
s
l
o
n
g i
n
t
e
g
e
r i
n
t
6
4 s
i
g
n
e
d 6
4 b
i
t
s
f
l
o
a
t n
u
m
b
e
r f
l
o
a
t
d
o
u
b
l
e n
u
m
b
e
r d
o
u
b
l
e
s
t
r
i
n
g s
t
r
i
n
g
b
y
t
e s
t
r
i
n
g b
y
t
e b
a
s
e
6
4 e
n
c
o
d
e
d c
h
a
r
a
c
t
e
r
s
b
i
n
a
r
y s
t
r
i
n
g b
i
n
a
r
y a
n
y s
e
q
u
e
n
c
e o
f o
c
t
e
t
s
b
o
o
l
e
a
n b
o
o
l
e
a
n
d
a
t
e s
t
r
i
n
g d
a
t
e A
s d
e
f
i
n
e
d b
y f
u
l
l

d
a
t
e R
F
C
3
3
3
9
d
a
t
e
T
i
m
e s
t
r
i
n
g d
a
t
e

t
i
m
e A
s d
e
f
i
n
e
d b
y d
a
t
e

t
i
m
e R
F
C
3
3
3
9
p
a
s
s
w
o
r
d s
t
r
i
n
g p
a
s
s
w
o
r
d U
s
e
d t
o h
i
n
t U
I
s t
h
e i
n
p
u
t n
e
e
d
s t
o b
e o
b
s
c
u
r
e
d
.

View Slide

Schemes
s
w
a
g
g
e
r s
t
r
i
n
g
R
e
q
u
i
r
e
d
. S
p
e
c
i
f
i
e
s t
h
e S
w
a
g
g
e
r S
p
e
c
i
f
i
c
a
t
i
o
n v
e
r
s
i
o
n
i
n
f
o I
n
f
o O
b
j
e
c
t R
e
q
u
i
r
e
d
. P
r
o
v
i
d
e
s m
e
t
a
d
a
t
a a
b
o
u
t t
h
e A
P
I
h
o
s
t s
t
r
i
n
g
T
h
e h
o
s
t (
n
a
m
e o
r i
p
) s
e
r
v
i
n
g t
h
e A
P
I
b
a
s
e
P
a
t
h s
t
r
i
n
g
T
h
e b
a
s
e p
a
t
h o
n w
h
i
c
h t
h
e A
P
I i
s s
e
r
v
e
d
, r
e
l
a
t
i
v
e t
o t
h
e
s
c
h
e
m
e
s [
s
t
r
i
n
g
] T
h
e t
r
a
n
s
f
e
r p
r
o
t
o
c
o
l
: "
h
t
t
p
"
, "
h
t
t
p
s
"
, "
w
s
"
, "
w
s
s
"
c
o
n
s
u
m
e
s [
s
t
r
i
n
g
] A l
i
s
t o
f M
I
M
E t
y
p
e
s t
h
e A
P
I
s c
a
n c
o
n
s
u
m
e
p
r
o
d
u
c
e
s [
s
t
r
i
n
g
] A l
i
s
t o
f M
I
M
E t
y
p
e
s t
h
e A
P
I
s c
a
n p
r
o
d
u
c
e
p
a
t
h
s P
a
t
h
s O
b
j
e
c
t R
e
q
u
i
r
e
d
. T
h
e a
v
a
i
l
a
b
l
e p
a
t
h
s a
n
d o
p
e
r
a
t
i
o
n
s f
o
r
.
.
.
h
t
t
p
:
/
/
s
w
a
g
g
e
r
.
i
o
/
s
p
e
c
i
f
i
c
a
t
i
o
n
/

View Slide

Demo Time!
http://petstore.swagger.io/

View Slide

Thank you!
https://slides.nils-loewe.de/
@NilsLoewe

View Slide

Introduction to Swagger

Introduction to Swagger

Nils Löwe

More Decks by Nils Löwe

Other Decks in Programming

Featured

Transcript