swagger for-your-api
DESCRIPTION
Slides from http://apistrategyconference.com/ on swagger in your REST apiTRANSCRIPT
Swagger for your REST API Tony Tam
REST as the “new” API
Revisiting the JAR
• Expose & share low-level functionality
• Reduced plumbing, focus on business logic
• Helped us build big, monolithic apps
• Dependency hell
REST as the “new” API
• Complex building blocks for your application • Authentication • Photo storage • Analytics
• Language & deployment independent
• Vertical scaling addressed by smaller, decoupled services
Integrating 3rd Party APIs
How about Documentation?"
Integrating 3rd Party APIs
How about Documentation?"
Javadocs?"
Stack Overflow?"
IDE support?"
JSDoc?"
Integrating 3rd Party APIs
Integrating 3rd Party APIs
Integrating 3rd Party APIs
Integrating 3rd Party APIs
So… How do we describe APIs?
Developer Docs?"
WADL"WADL2?"
WSDL?"
Javadocs?"
The Swagger Specification
It’s a spec! • JSON • Coupled of decoupled • Machine-readable • Language agnostic • Distributed by Design
An Interface for your API
Benefits of an Interface
It’s done in JSON • Generate manually
• Deploy statically • Generate automatically by server integration
• 9 languages, 16+ frameworks
Existing API?
Benefits of an Interface
Machine-readable Your boss can try your
API
Swagger Spec Server"
Benefits of an Interface
Distributed design
/pet"
/store"
/user"
Server 1"
Server 2"
Server 3"
Resource"Listing"
API Declaration"
How does this help you?
Client-Side Developer"
Server"Developer"
How does this help you?
Client-Side Developer"
OMG I can code w/o waiting for back end!"
The client developer
isn’t bugging me!"
Server"Developer"
How about your clients?
REST or SDK? • Please! Strive to
remove your logic from clients
/api/pet.json/1?delete (GET) /api/pet.json/1 (DELETE) /api/pet.json/1 (POST empty)
How about your clients?
REST or SDK? • Please! Strive to
remove your logic from clients
/api/pet.json/1?delete (GET) /api/pet.json/1 (DELETE) /api/pet.json/1 (POST empty) These all
“work” (This is your job, not your
clients’)
How about your clients?
Swagger can help (if you like) • Machine-readable => code generator • Uses non-ghetto {{mustache}} templates • Make client libraries “your way”
How about your API service?
Swagger can again help (if you like) • Code-generator, not “client generator” • Build your server from the interface
Interfaces are nice
• Developers know what they’re building • Clients know what they’re getting • Machines and humans can interpret them • Teams can develop in parallel
Swagger is FOSS
Where to go next More info + demo http://developers.helloreverb.com/swagger/
Swagger specification https://github.com/wordnik/swagger-core/wiki
JVM server implementation https://github.com/wordnik/swagger-core
Node.js server implementation https://github.com/wordnik/swagger-core
swagger-ui https://github.com/wordnik/swagger-ui
swagger-codegen https://github.com/wordnik/swagger-codegen
@fehguy"