simple rest-apis with dropwizard and swagger

SimpleREST-APIswithDropwizard andSwagger

BerndSchönbachLeanIX GmbH

@boernd_s

Motivation

2REST-APIswith Dropwizard &Swagger – VoxxedDays Berlin2016– BerndSchönbach– LeanIX GmbH

- QuicklycreateREST-APIs

- Makethemtestable

- Makethemdeployablewithaclick

- Orevenbetterautomatically

- ProvideDocumentationwithoutMSOffice

- ProvideSDKwithnoextraactionneeded

Overview


Introduction• Aboutme• AboutLeanIX

Dropwizard• SetUp/BasicFeatures• Demo• AdvancedFeatures

Swagger+SwaggerUI• SetUp/BasicFeatures• Demo• AdvancedFeatures

Introduction

Aboutme


EnvironmentBernd Schönbach

• Est.:1982• FirstLanguage:PHP(2001)• SecondLanguage:Java(2010)• Java-Dev. @leanIX:2015-

LeanIXwasborn,since pragmatic solutions forITArchitecture Managementdid notexist


JörgG.Beyer AndréChrist

Management-Team&FounderLeanIX GmbH

• Headquarter:Bonn• Founded:01/2012• Launch:08/2012

• 4yearsManagementConsulting@DHL

• 8yearsFreelancerSoftwareDesign&Architecture

• Speaker&AuthorforSoftwareArchitecture

• 10yearsITLeadership@DHL,e.g.globalCIO

• 4yearsMDfornewlyestablishedITManagementConsulting

• 10yearsConsulting:Andersen&self-employed

LeanIXhelpscompaniestomanageandoptimizetheirITArchitectures


Current ITArchitecture CreateTransparency Optimize ITArchitecture

• Missinginformation(e.g.interfaces,technologies)

• Hardtointroducenewproducts&saleschannels

• Highcostsandrisks

• ImportexistingdataintoLeanIX(viaExcelorAPI)

• Inviteexpertstosharetheirknowledge

• Usebest-practicereportstoidentifyissues

• Definetargetarchitectureandroadmaps

Learn more: https://www.leanix.net/en/product/index

https://www.leanix.net/en/product/index

LeanIXisaweb-basedplatformtocaptureandshareknowledgeaboutIT


FactSheets&Tagging

Context-basedSearch

API,Import&Export

Comments&Threads

ITInventory CollaborationPlatform InteractiveReporting

ActivityStream&Notifications

Subscriptions

Print&Export(PDF)

BestPracticeReports

InteractiveAdaption

Learn more: https://www.leanix.net/en/product/index

https://www.leanix.net/en/product/index

Marketleading companies already use LeanIX

9

Media

Insurance

Industry

e-Commerce

Telecoms

Chemical

Advisory

Government

Manufacturing

Logistics

Education

Health

Energy

See more: https://www.leanix.net/en/customers/index

https://www.leanix.net/en/customers/index

Dropwizard

Dropwizard


LiveDemo

Overview

Whatisit?

TheBasics

Advanced Features

• JavaFrameworkfor RESTful WebServices

• QuickStartup(few seconds)

• Completely configurable

• Current Version:0.9.2(we willbe using 0.9.1)

Dropwizard


LiveDemo

Overview

Whatisit?

TheBasics

Advanced Features

• FrameworkContents:• Jetty for HTTP• Jerseyfor REST• Jacksonfor JSONtransformation• Hibernate for DBAccess

•Otherusefull inclusions•Metrics• Liquibase• Slf4jand Logback• and much more...

Dropwizard


FirstSteps:

Whatisit?

TheBasics

Advanced Features

• CreateMavenProject

• Adddependencytodropwizard

• ConfigureMavenShadePlugin

• Addconfigurationfile(optional)

• Startcoding

Dropwizard


Adddependency to pom.xmlStandardway (dropwizard only)

Whatisit?

TheBasics

Advanced Features

<properties><dropwizard.version>0.9.1</dropwizard.version></properties>

Step1:

Step2:

<dependencies><dependency><groupId>io.dropwizard</groupId><artifactId>dropwizard-core</artifactId><version>${dropwizard.version}</version></dependency></dependencies>

Dropwizard


Adddependency to pom.xmlOur way (Swagger &Dropwizard together)

Whatisit?

TheBasics

Advanced Features

<properties><dropwizard.version>0.9.1-1</dropwizard.version></properties>

Step1:

Step2:

<dependencies><dependency><groupId>com.smoketurner</groupId><artifactId>dropwizard-swagger</artifactId><version>${dropwizard.version}</version></dependency></dependencies>

Dropwizard


Configure Maven Shade Plugin

Whatisit?

TheBasics

Advanced Features

<plugin><artifactId>maven-shade-plugin</artifactId><version>2.4.1</version><executions><execution><phase>package</phase><goals><goal>shade</goal></goals><configuration combine.children="append"><createDependencyReducedPom>true</createDependencyReducedPom><outputFile>target/voxxed-test.jar</outputFile>[...]</configuration></execution></executions></plugin>

Let’scode!

Dropwizard


Configure your Application

Whatisit?

TheBasics

Advanced Features

config.yml

server:applicationConnectors:type: httpport: 1337

adminConnectors:type: httpport: $env:ADMIN_PORT:1338

Logging:level: INFOFooBar: Value

Dropwizard


Resource Methods and Paths

Whatisit?

TheBasics

Advanced Features

@Path(“persons”)public class PersonResource {

@GETpublic String getPersons () {[…]}

@PUTpublic StringupdatePerson(){[…]}

@POSTpublic StringcreatePerson(){[…]}

@DELETEpublic StringdeletePerson(){[…]}

URL:localhost:1337/persons

@GET@Path("/address"}public StringgetPersonAddress(){[…]}

URL:localhost:1337/persons/address

Dropwizard


Queryand PathParams

Whatisit?

TheBasics

Advanced Features

Task1:SearchanEntity.URL:http://localhost:1337/persons?name=adam

Task2:RetrieveanEntity:URL:http://localhost:1337/persons/1234/

QueryParameterspublic class PersonResource {@GETpublic String getPerson(@QueryParam(“name”) String name) {[…]}

PathParameterspublic class PersonResource {@GET@Path(“/{id}”)public String getPersonById(@PathParam(“id”) String id) {[…]}

Dropwizard


ResponseTypes

Whatisit?

TheBasics

Advanced Features

ReturnandretrieveJSON

@Produces(MediaType.APPLICATION_JSON)@Consumes(MediaType.APPLICATION_JSON)public class PersonResource {

@GETpublic String getPerson (@QueryParam(“name”) String name) {[…]}

@Produces(MediaType.APPLICATION_JSON)@Consumes(MediaType.APPLICATION_JSON)public class PersonResource {


@GET@Path(“xml”)@Produces(MediaType.APPLICATION_XML)public String getPersonXml (){[…]}

Dropwizard


Whatisit?

TheBasics

Advanced Features

AdvancedFeatures

- HATEOAS

- ValidatorsandDefaultsforQueryParameters

- AuthenticationHandling

Dropwizard


Pimping your Response(HATEOAS)

- AddMetaInformationtoResponseData

- ProvideLinkstoallowautomatedtraversal(bymachines)

{data:[{…},…,{…}]size:10total:150links:{next:“/persons/page=2&limit=10”,current:“/persons/page=1&limit=10”,previous:null}}

Whatisit?

TheBasics

Advanced Features

Dropwizard


Pimping your Response(HATEOAS)ResponseObjects

Whatisit?

TheBasics

Advanced Features

public class BasicResponse {protected ResponseStatus status = ResponseStatus.OK;protected String type;protected Stringmessage;protected Long total;[…]}

public class PersonResponse extends BasicResponse {protected Persondata;protected Linkslinks;

public class Links{protected String next;protected String previous;protected String current;}}

Dropwizard


Pimping your Response(HATEOAS)OptionB:JerseyLinks

Whatisit?

TheBasics

Advanced Features

public void run(AppConfig conf,Environmentenv)throws Ex{environment.jersey().getResourceConfig().packages(getClass().getPackage().getName()).register(DeclarativeLinkingFeature.class);

}

App.java

- Adddependencytojersey-server-linking- RegisterinrunfunctionofApp.java- Add@Linkor@RefAnnotations

ForfurtherInformationsee:https://jersey.java.net/documentation/1.19/linking.html

Dropwizard


Validators and DefaultsforQueryParameters

Whatisit?

TheBasics

Advanced Features

public class PersonResource {


public class PersonResource {

@GETpublic String getPerson (@QueryParam(“name”) @NotEmpty String name) {[…]}

Validating:

SuppliedbyHibernateValidator

@NotNull@Min(Integer);@Max(Integer)@Size(min=Integer,max=Integer)

@Future,@Past@Pattern(regex=String)

@Valid

Dropwizard


AuthenticationHandling

Whatisit?

TheBasics

Advanced Features

Step1:CreateAuthenticationProvider:

public class ExampleAuthenticator implementsAuthenticator<BasicCredentials,User>{@Overridepublic Optional<User> authenticate(BasicCredentials credentials) throws AuthenticationException{if ("secret".equals(credentials.getPassword())) {return Optional.of(new User(credentials.getUsername()));}return Optional.absent();}}

Dropwizard



Whatisit?

TheBasics

Advanced Features

Step2:RegisterAuthenticationProvider:

public void run(AppConfig conf,Environmentenv)throws Ex{environment.jersey().register(new AuthDynamicFeature(new BasicCredentialAuthFilter.Builder<User>().setAuthenticator(new ExampleAuthenticator()).setRealm("SUPERSECRETSTUFF") .buildAuthFilter()

));environment.jersey().register(RolesAllowedDynamicFeature.class);environment.jersey().register(new AuthValueFactoryProvider.Binder<>(User.class));}

Dropwizard



Whatisit?

TheBasics

Advanced Features

Step3:UseAuth Parameter:

public class PersonResource {@GETpublic String getPerson (@QueryParam(“name”) @NotEmpty String name,@Auth Userauth ){[…]}}

Swagger+

SwaggerUI

Swagger


Swagger +Swagger UI

Whatisit?

TheBasics

Advanced Features

- SimpledocumentationforRESTAPIs

- AllowsautomaticSDKGeneration

- NiceandinteractiveUserInterface

Swagger Workflow


JSONSpecification

HTMLAPIUI

SDKGeneration

CodeAnnotation

Let’scode!

Swagger


BasicAnnotations

Whatisit?

TheBasics

Advanced Features

@Api(“Description”)

@ApiResponse@ApiResponses

@ApiOperation(value=String,notes=String,response=Class,responseContainer =String)

@ApiParam()@DefaultValue(mixed)

Swagger


BasicAnnotations

Whatisit?

TheBasics

Advanced Features

@ApiParam(name=String,value=String,

defaultValue =String,required=Boolean,

allowableValues =String,example=String,hidden=Boolean)

Swagger


FurtherAnnotations

Whatisit?

TheBasics

Advanced Features

@ApiModel(value=String,description=String)

@ApiModelProperty(value=String,allowableValues=String)

@Contact

@License

Swagger


LiveDemo

Advanced FeaturesSDKGeneration

Whatisit?

TheBasics

Advanced Features

Example for PHPand Java:https://github.com/leanix/swagger-demo-codegen

Configuration for that:https://goo.gl/plH6pB

Thank you!

Learn More about LeanIX

Share on LinkedIn

http://bit.ly/LeanIXDemoS

Request free demohttp://bit.ly/LeanIXDemoS

http://bit.ly/LeanIXDemoS

https://www.linkedin.com/shareArticle?mini=true&url=http://www.slideshare.net/leanIX_net/simple-restapis-with-dropwizard-and-swagger-57646748

http://bit.ly/LeanIX-Slideshare

Questions?

Sources

REST-APIswith Dropwizard &Swagger – VoxxedDays Berlin2016– BerndSchönbach– LeanIX GmbH

• Dropwizard: http://www.dropwizard.io/

• Swagger: http://swagger.io/

• Swagger-UI: http://swagger.io/swagger-ui/

• HibernateValidator: http://hibernate.org/validator/

• Dropwizard SwaggerPackage: https://github.com/smoketurner/dropwizard-swagger

Slideswillbeavailableat

REST-APIswith Dropwizard &Swagger – VoxxedDays Berlin2016– BerndSchönbach– LeanIX GmbH

LeanIXWebsite:https://www.leanix.net/

LeanIXBlog:http://blog.leanix.net/

Slideshare:http://slideshare.net/leanIX_net/

Share on LinkedIn

http://bit.ly/LeanIX-Slideshare

http://blog.leanix.net/

http://slideshare.net/leanIX_net/

https://www.linkedin.com/shareArticle?mini=true&url=http://www.slideshare.net/leanIX_net/simple-restapis-with-dropwizard-and-swagger-57646748

simple rest-apis with dropwizard and swagger

Technology