Upload
tony-tam
View
387
Download
1
Embed Size (px)
Citation preview
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, structured way to describe your API
• Methods, Resources, Parameters, media types
• Everything your consumers need to know to consume your API
Swagger Example
JSON
For Robots
Swagger Example
YAML
For Humans
Swagger ExampleTaken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
API Metadata
Swagger ExampleTaken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Host Metadata
Swagger ExampleTaken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Resources
Swagger ExampleTaken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Organizational Tags
Swagger ExampleTaken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Codegen Hints
Swagger ExampleTaken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Parameters
Swagger ExampleTaken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Expected Responses
Swagger ExampleTaken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Response Payload
Swagger ExampleTaken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Model Schemas
Swagger ExampleTaken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0
Required Properties
Swagger ExampleTaken 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
Definition drives the code
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)
Annotation Example
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
Design First Example
Architecting for MaintainabilityWhoever
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 drive your API, not just document it
• You have a DSL, use it!
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
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
Example projecthttps://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].name
• Explicitly set as operation extension– x-swagger-router-controller: org.your.Controller
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
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)
Complex Arguments
1. Matched by mapping in inflector.yaml2. Extension on model3. “Raw” JsonNode
public ResponseContext addMeetup (RequestContext request, JsonNode meetup)
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 development!
Back-EndFront-End
Auto-gen SDK
Mock Data
AdminController
UsersController
LoginController
Incremental Impl!
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 Conversion?– Implement a Converter
• Custom Input Validation?– Implement a Validator
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
Thank you!