API Design first with Swagger

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!