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.

1. Putting API Design First with
Swagger
Tony Tam
@fehguy

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

3. Swagger Example
JSON
For
Robots

4. Swagger Example
YAML
For
Humans

5. Swagger Example
Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
API Metadata

6. Swagger Example
Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Host Metadata

7. Swagger Example
Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Resources

8. Swagger Example
Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Organizational Tags

9. Swagger Example
Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Codegen Hints

10. Swagger Example
Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Parameters

11. Swagger Example
Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Expected Responses

12. Swagger Example
Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Response Payload

13. Swagger Example
Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Model Schemas

14. Swagger Example
Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Required Properties

15. Swagger Example
Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Properties and Datatypes

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)

18. Annotation Example

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

20. Design First Example

21. Architecting for Maintainability
Whoever
thought of
this was an
*#&&!
Let’s go with
a dramatic,
50 pitch roof

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

25. Example project
https://github.com/fehguy/javaone-inflector-demo

26. Setup
• Add dependency
• Enable as JaxRS Application

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

30. Finding Methods
• Method name
– Controller Class + explicit operationId
• operationId: myMethod
– Controller Class + generated operationId
• operationId: clean(path) + httpMethod
– Explicit extension
• x-swagger-router-controller:
org.your.Controller.methodName

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!

34. Hitting Endpoints
• Response schema declares array!
Schema
Validation!

35. Input Parameters
• Design it the right way!

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!

37. Incremental Development
• What’s done? What’s Missing?

38. Incremental Development
• Moving to through SDLC

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

41. Thank you!