Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Putting API Design First with
Swagger
Tony Tam
@fehguy
What is Swagger?
• The basis of the Open API Specification
– A Linux Foundation Project
– https://openapis.org
• A simple,...
Swagger Example
JSON
For
Robots
Swagger Example
YAML
For
Humans
Swagger Example
Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
API Metadata
Swagger Example
Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Host Metadata
Swagger Example
Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Resources
Swagger Example
Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Organizational Tags
Swagger Example
Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Codegen Hints
Swagger Example
Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Parameters
Swagger Example
Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Expected Responses
Swagger Example
Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Response Payload
Swagger Example
Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Model Schemas
Swagger Example
Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Required Properties
Swagger Example
Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Properties and Datatypes
How do you create a Swagger?
• It’s just a JSON or YAML document!
– Code First
– Design First
Code drives
the Definition
D...
Code First
• Code Annotations, comments for
embedded documentation
– Processed at compile-time, post-compile,
runtime
– Do...
Annotation Example
Design First
• Start with the Swagger Definition as a
blueprint for the implementation
– Code from the definition
• Manual...
Design First Example
Architecting for Maintainability
Whoever
thought of
this was an
*#&&!
Let’s go with
a dramatic,
50 pitch roof
Removing the Cruft
• Keep documentation outside your code
• Don’t clutter up your code!
– Use the Swagger Definition to dr...
Introducing Swagger Inflector
• Use Swagger as the Source of Truth for
the API
– Automatically route to controllers
– Auto...
How does it work?
• Inflector loads a Swagger Definition at startup
• Parses routes, parameters, models
• Uses configurati...
Example project
https://github.com/fehguy/javaone-inflector-demo
Setup
• Add dependency
• Enable as JaxRS Application
Setup
• Create and configure inflector.yaml
• Save a swagger specification
Run it!
... Now what?
• Definition parsed, loaded
• Swagger definition mounted at basePath
Finding Controllers
• Default location from inflector.yaml
• Class name from Tag convention
– controllerPackage + tag[0].n...
Finding Methods
• Method name
– Controller Class + explicit operationId
• operationId: myMethod
– Controller Class + gener...
Finding Methods
• Method Arguments
– Response class match
• io.swagger.inflector.models.ResponseContext
– Argument match
•...
Complex Arguments
1. Matched by mapping in inflector.yaml
2. Extension on model
3. “Raw” JsonNode
public ResponseContext
a...
Hitting Endpoints
• No implemented controller! Get mock data
• Implement a controller…
But it’s
Wrong!
Hitting Endpoints
• Response schema declares array!
Schema
Validation!
Input Parameters
• Design it the right way!
Putting Inflector in Practice
• Complete decoupling of API definition from
business logic
• Define API, concurrent develop...
Incremental Development
• What’s done? What’s Missing?
Incremental Development
• Moving to through SDLC
Extend it as needed
• Security?
– Use the RequestContext!
• Content Types?
– Implement an EntityProcessor
• Type Conversio...
Swagger Connected
• Swagger is FOSS
• Specification + Tools at http://swagger.io
• All source at https://github.com/swagge...
Thank you!
Upcoming SlideShare
Loading in …5
×

API Design first with Swagger

1,757 views

Published on

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.

Published in: Technology
  • Be the first to comment

API Design first with Swagger

  1. 1. Putting API Design First with Swagger Tony Tam @fehguy
  2. 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. 3. Swagger Example JSON For Robots
  4. 4. Swagger Example YAML For Humans
  5. 5. Swagger Example Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0 API Metadata
  6. 6. Swagger Example Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Host Metadata
  7. 7. Swagger Example Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Resources
  8. 8. Swagger Example Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Organizational Tags
  9. 9. Swagger Example Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Codegen Hints
  10. 10. Swagger Example Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Parameters
  11. 11. Swagger Example Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Expected Responses
  12. 12. Swagger Example Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Response Payload
  13. 13. Swagger Example Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Model Schemas
  14. 14. Swagger Example Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Required Properties
  15. 15. Swagger Example Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Properties and Datatypes
  16. 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. 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. 18. Annotation Example
  19. 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. 20. Design First Example
  21. 21. Architecting for Maintainability Whoever thought of this was an *#&&! Let’s go with a dramatic, 50 pitch roof
  22. 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. 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. 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. 25. Example project https://github.com/fehguy/javaone-inflector-demo
  26. 26. Setup • Add dependency • Enable as JaxRS Application
  27. 27. Setup • Create and configure inflector.yaml • Save a swagger specification
  28. 28. Run it! ... Now what? • Definition parsed, loaded • Swagger definition mounted at basePath
  29. 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. 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. 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. 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. 33. Hitting Endpoints • No implemented controller! Get mock data • Implement a controller… But it’s Wrong!
  34. 34. Hitting Endpoints • Response schema declares array! Schema Validation!
  35. 35. Input Parameters • Design it the right way!
  36. 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. 37. Incremental Development • What’s done? What’s Missing?
  38. 38. Incremental Development • Moving to through SDLC
  39. 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. 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. 41. Thank you!

×