A look at the latest from the Swagger team, including a Swagger 2.0 overview, the Swagger Editor, and design-first API development using Swagger 2.0

1.
The
Latest
and
Greatest
James
Higginbotham
@launchany

2. SWAGGER
–
OVERVIEW

3.
Swagger
is
a
simple
yet
powerful
representa<on
of
your
RESTful
API.

4. Drives
API
Documenta>on

5. Without
Swagger
Defini>on

6. With
Swagger
Defini>on

7. Swagger
Structure
-­‐
Info

8. Swagger
Structure
-­‐
Paths

9. Swagger
Structure
-­‐
Security

10. Swagger
Structure
–
Security
Types

11. Swagger
Structure
-­‐
Defini>ons

12. Swagger
Data
Types

13. Swagger
is
much
bigger
than
Swagger-­‐UI

14. Swagger
Ecosystem

15. Beyond
Interac>ve
Docs

16. Beyond
Defini>on:
Visualiza>on
Swagger.ed
hMps://github.com/chefArchitect/apispots-­‐browser-­‐swaggered

17. Swagger
2.0
u Released
last
year
u Evolve
the
JSON
syntax
u Add
support
for
human-­‐friendly
format
u Vendor
extensions
support

18. From
Reverb
to
SmartBear

19. Community
Contribu>ons
Growing!

20. New:
Community-­‐Driven
Website
u New
website
underway
–
hMp://swagger.io
– Github
driven
– Pages
have
a
“View
Source
on
Github”
link
– For
the
community,
BY
the
community
– Feel
free
to
contribute
content

21. June
6
Release
u SmartBear
tools
now
have
2.0
support
throughout
u Swagger
JS/UI
– Now
upgrade
older
versions
of
Swagger
2.0
before
processing
– Major
rewrites
of
the
underlying
libraries
of
these
projects
u Core
and
Codegen
– Completely
rewriMen
in
Java
(used
to
be
Scala)
– BeMer
extension
mechanism
to
allow
for
core
customiza>ons
– Codegen
has
new
templates
(Swic,
Perl,
updated
JAX-­‐RS)
u Governance
– Crea>ng
an
open
governance
model
for
the
spec
– Will
involve
other
companies
and
individuals
– S>ll
figuring
out
the
exact
model
(before
the
end
of
June)

22. SWAGGER
FOR
A
DESIGN-­‐FIRST
API

23. Design
First
API
Approach

24. Design
First
API
Lifecycle
u Design
the
API
contract
u Mock
the
API
for
valida>on/collabora>on
u Test
for
compliance/completeness
u Build
the
implementa>on
u Deploy
u Manage
Fast
feedback
loops,
collabora>ve
development

25. Swagger
Support
for
Design-­‐First
u Swagger
always
top-­‐down
capable
u However,
tooling
focused
on
boMom-­‐up
u History
of
fragmented
tool
ecosystem

26. Introducing
Swagger
Editor

27. YAML
for
the
Human
swagger:
'2.0'
info:
version:
1.0.0
>tle:
A
simple
API
paths:
/:
get:
responses:
200:
descrip>on:
OK

28. JSON
for
the
Tools
{
"swagger":
"2.0",
"info":
{
"version":
"1.0.0",
">tle":
"A
simple
API"
},
"paths":
{
"/":
{
"get":
{
"responses":
{
"200":
{
"descrip>on":
"OK"
}
}
}
}
}
}

29. Swagger
Tools:
Documenta>on
Swagger
Editor:
Design
your
API
using
simple
YAML
format,
preview.
Requires
the
Node.js
app.
Swagger
UI:
Display
your
documenta>on
using
sta>c
HTML
and
client-­‐side
Javascript.
No
Node.js
required.

30. Swagger
Tools:
Code
Genera>on

31. Swagger-­‐Based
Tes>ng
SoapUI:
Import
and
generate
tests
using
SmartBear’s
SoapUI
tool.
Runscope:
Import
Swagger
and
generate
run>me
tests
using
Runscope.

32. Op>on
1:
Hosted
u Editor
hMp://editor.swagger.io/
u Generators
w/
API
hMp://generator.swagger.io/

33. Op>on
2:
Install
and
Customize
hMps://github.com/swagger-­‐api/swagger-­‐generator
hMps://github.com/swagger-­‐api/swagger-­‐editor

34. Editor
Extensions
Swagger
Editor
Callbacks:
Callbacks
for
integra>ng
with
design/deploy
workflows.
Swagger
Editor
Storage:
Backend
support
using
GET
and
PUT
for
retrieving
and
saving
YAML
defini>ons.

35. How
to
Get
Started
with
Swagger
u Use
the
Swagger
Editor
to
view
samples
u In
parallel,
read
the
Swagger
2.0
Spec
to
understand
samples
in-­‐depth
u Reverse-­‐engineer
exis>ng
API
or
third-­‐party
API
into
Swagger
u Publish
using
Swagger-­‐UI
u Try
one
of
the
client
code
generators
(some
beMer
than
others)

36. Thanks
Ya’ll
James
Higginbotham
james@launchany.com
hMp://launchany.com
@launchany