Presented at JavaOne 2016.
Using Swagger has become the most popular way to describe REST APIs across the web, enabling people to more quickly understand and communicate with services, with developer-friendly documentation and rich, autogenerated client SDKs. As the API has moved more into being one of the most important aspects of a service, the Swagger definition has become increasingly more important and essential to the design phase. This presentation explains how the Swagger definition can be used to streamline the iteration process and enable client and server engineers to develop concurrently with complex APIs.
2. What is Swagger?
• The basis of the Open API Specification
– A Linux Foundation Project
– https://openapis.org
• A simple, structured way to describe your
API
• Methods, Resources, Parameters, media
types
• Everything your consumers need to know
to consume your API
16. How do you create a Swagger?
• It’s just a JSON or YAML document!
– Code First
– Design First
Code drives
the Definition
Definition
drives the code
17. Code First
• Code Annotations, comments for
embedded documentation
– Processed at compile-time, post-compile,
runtime
– Docs are always right! (code is the
documentation)
• Like Javadocs for REST APIs (but tons better)
19. Design First
• Start with the Swagger Definition as a
blueprint for the implementation
– Code from the definition
• Manual! Swagger Definition is just the
implementation guideline
• Automated with swagger-codegen
22. Removing the Cruft
• Keep documentation outside your code
• Don’t clutter up your code!
– Use the Swagger Definition to drive your API,
not just document it
• You have a DSL, use it!
23. Introducing Swagger Inflector
• Use Swagger as the Source of Truth for
the API
– Automatically route to controllers
– Automatically map models
– Generate Sample Data when controllers not
implemented
https://github.com/swagger-api/swagger-inflector
24. How does it work?
• Inflector loads a Swagger Definition at startup
• Parses routes, parameters, models
• Uses configuration / extensions to find
controllers by method signature
– If a controller doesn’t exist, produces mock data
• Routes requests to the Right Place
• No Magic™ Software
– Jersey 2.x
– Jackson 2.x
27. Setup
• Create and configure inflector.yaml
• Save a swagger specification
28. Run it!
... Now what?
• Definition parsed, loaded
• Swagger definition mounted at basePath
29. Finding Controllers
• Default location from inflector.yaml
• Class name from Tag convention
– controllerPackage + tag[0].name
• Explicitly set as operation extension
– x-swagger-router-controller: org.your.Controller
31. Finding Methods
• Method Arguments
– Response class match
• io.swagger.inflector.models.ResponseContext
– Argument match
• io.swagger.inflector.models.RequestContext
• Arguments matching ordered operation parameters
public ResponseContext
getMeetups (RequestContext request,
String title)
32. Complex Arguments
1. Matched by mapping in inflector.yaml
2. Extension on model
3. “Raw” JsonNode
public ResponseContext
addMeetup (RequestContext request,
JsonNode meetup)
33. Hitting Endpoints
• No implemented controller! Get mock data
• Implement a controller…
But it’s
Wrong!
36. Putting Inflector in Practice
• Complete decoupling of API definition from
business logic
• Define API, concurrent development!
Back-EndFront-End
Auto-gen
SDK
Mock
Data
AdminController
UsersController
LoginController
Incremental
Impl!
39. Extend it as needed
• Security?
– Use the RequestContext!
• Content Types?
– Implement an EntityProcessor
• Type Conversion?
– Implement a Converter
• Custom Input Validation?
– Implement a Validator
40. Swagger Connected
• Swagger is FOSS
• Specification + Tools at http://swagger.io
• All source at https://github.com/swagger-api
• Real-time support at irc.freenode.net
#swagger