Jcon 2017 How to use Swagger to develop REST applications

(HOW TO) USE SWAGGER TO
DEVELOP REST APPLICATIONS
@johannes_fiala - JCON 2017

About me…
 Swagger-CodegenContributor
 Javascript, Jaxrs-CXF, BeanValidation for Java*,
Jaxrs-Resteasy
 Other contributions
 Spring REST / Swagger-Springfox
 BeanValidation support
 Swagger2Markup
 BeanValidation support

Agenda
 Generate based on contract
 Extend using code first
 Freeze the contract
 Use the RESTAPI
 Generate client code (Java/Javascript)
 Access with a browser using a UI
 View/Share as HTML/PDF
 Customize the code generator

Toolchain
 ApacheCXF 3
 + SwaggerFeature
 + Spring integration/Spring Boot integration
 Swagger-Tools
 Swagger-Editor / Eclipse KaiZen Plugin
 Swagger-Codegen
 Swagger-UI
 Swagger2Markup

Contract first, then code,
then contract …

Contract spec. formats
 WADL (XML-based)
 By w3c, Last update 2009
 Swagger (Json/Yaml-based)
 By Linux foundation
 Version 1.0 – 2011 (Wordnik)
 Version 1.2 - 2014
 Version 2.0 – 2015 / transferred to Linux foundation /
Open-API initiative
 Version: 3.0 (released 2017-07)
 Others: Blueprint, RAML, …

Open API / Swagger
 A language-agnostic interface to RESTAPIs
 allows to discover and understand the
capabilities of a service
 Supported Formats: JSON/YAML
https://github.com/OAI/OpenAPI-Specification

Contract editors
 Swagger Editor
 by SmartBear
 Eclipse SwagEdit
 By RepreZen API Studio
 Neu: KaiZen – für OpenAPI 2 + 3
 Templates nur fürYaml, nicht für Json
 CommercialTools:
 Restlet Studio
 RepreZenAPI Studio

Eclipse + KaiZen Plugin
 Open Source
 https://github.com/RepreZen/KaiZen-OpenAPI-Editor
 Swagger 2 + 3
 Supports onlyYAML format
 Navigation
 Outline
 + Navigate using Ctrl+Click
 Templates
 Scope-specific
 Completely Customizable!

Templates

 Demo

Swagger-Codegen
 by SmartBear (Apache License)
 Version 2.2.3
 Java program
 + Mustache templating
 Generates server + client code
 Currently supports OpenAPI v2 !
 Support for 3.0 in progress…, see #6517
https://github.com/swagger-api/swagger-codegen

Swagger-Codegen
Supported Languages
 Client and/or Server available for:
 Android,Asp.net, AsyncScala, Bash, Clojure,ConfluenceWiki,
C++, C#, Dart, Elixir, Erlang, Finch, Flash, FlaskConnexion, Go,
Groovy, Haskell, Java,CXF, JavaInflector, Jaxrs-Spec, Jersey,
JavaMSF4J, Resteasy, Javascript,AngularJS, Jmeter, Lumen,
NancyFX, NodeJS, ObjC, Perl, Php, Python,Qt5C++, Rails,
Ruby, Scala, Scalatra, Silex, Sinatra, Slim (PHP), Spring, Static
Html, Swagger,Yaml, Swift,Tizen,TypescriptAngular,
Undertow, …
 And many more libraries (e.g. Java Jersey1, ok-http-gson, …)

Jcon 2017 How to use Swagger to develop REST applications

Generate the server stub
Swagger-Codegen
 Supported server stubs for Java:
 Java JAX RS
 2.0 spec
 Jersey
 CXF (Spring/CDI)
 Resteasy
 Spring MVC
 Spring Boot

CXF server stub
Features
 Since 2.2.2 (released 2017-03-01)
 Generates Interface/Implementation/Models
 Generate a complete web application
 Context.xml / ApplicationContext.xml
 Web.xml
 Jboss: jboss-web.xml
 Spring Boot support
 Run as Spring-Boot Application
 Run using Spring Integrationtests using random
ports

CXF server stub
Supported Features
 Spring application
 Swagger generator
 WADL generator
 BeanValidation annotations
 Activate automatic BeanValidation (1.1)
 Compression (gzip)
 Logging
 Integration-Tests (Spring Boot)

Swagger-Codegen CLI
 io.swagger.codegen.Codegen
-i hello_world.json
-l jaxrs-cxf
-o c:hello_world_project
-c hello_world_config.json

Demo
 Create hello world service
 GenerateCXF server stub (with Spring
support enabled)
 Run using Spring Boot
 Run Junit-Tests
 Deploy to application server (Jboss EAP 7)

Swagger-Codegen CLI
Display all language options
 io.swagger.codegen.SwaggerCodegen
config-help -l jaxrs-cxf
or
 java -jar modules/swagger-codegen-
cli/target/swagger-codegen-cli.jar config-
help –l jaxrs-cxf

Generated Code – Hints
 Enum references supported (for models)
 Inheritance supported (but merged from
parent classes)
 BeanValidation
(@Min/@Max/@Size/@Pattern/@Valid)
 Builder pattern for models:
 return new Response().name(“Foo").first(“Test”);
 Optionally use JaxRs-Response instead of
return datatypes (useGenericResponse-flag)

Further development
life cycle
 Extend the API
 code first
 Use theAPI
 Frontend development

Extend the application
 Modify your API:
 Add new services (use JAXRS-annotations)
 Use Swagger annotations
 Use BeanValidation annotations
 Generated Swagger spec gets updated
automatically

Extend the application
Swagger annotations
 Service:
 @Api – activate Swagger for api
 Operations:
 @ApiOperation - description
 @ApiResponse – error codes + return types
 Model:
 @ApiModel - description
 @ApiModelProperty - description

Freeze your API:
 Generate only interfaces/models
 Prevent accidential changes of theAPI
 Integrate in build job (Maven / Gradle)
 Specify which sources should NOT be
generated during build using .swagger-
codegen-ignore
 https://github.com/swagger-api/swagger-
codegen/tree/master/modules/swagger-codegen-maven-plugin

Freeze your API: maven
configuration

Demo
 Extend hello world service
(+ BeanValidation)
 Access updated specs

Use your API
 Generate client stubs
 Swagger-Codegen
 Access your API using a browser
 Swagger-UI
 Generate HTML/PDF documentation
 Swagger2Markup

Why generate client code?
 No more manual api calls
 Ensure consistency of your client code with
theAPI!
 Makes code completion possible!
 Allows developers to read description for
your operations and models in the IDE
 You get compilation errors if the API breaks
with newer versions!

Swagger-UI
 By SmartBear
 Access your API with a browser
 Javascript application
 Can access the generated Swagger spec – always
consistent with your code
 Integration options:
 Copy into your webapp
 load asWeb-Jar
https://github.com/swagger-api/swagger-ui

Swagger2Markup
 By RobertWinkler (github)
 Render your API in HTML/PDFs
 Uses Markdown/Asciidoctor files
 Completely customizable
 Integration options:
 Run as Program/Unittest
 Maven
https://github.com/Swagger2Markup/swagger2markup

Swagger2Markup
Swagger
contract
Asciidoctor Html
PDF

Swagger2Markup
Improve the docs
 Automatically added:
 Since 1.0.1:Validation constraints are added
automatically to the properties
 Example values for Models are added as Example
HTTP responses
 „Polymorphism: Composition“ added for
inheriting models
 Manually: Add description to your models
and operations

Demo
 Client stub generator:
 Java
 Swagger-UI
 Swagger2Markup

Customize the generator
 Generator implemented in Java (one class for
each language)
 Mustache-files
 api.mustache
 apiServiceImpl.mustache
 pojo.mustache
 api_test.mustache
 …

 Use –t flag for your own templates
 Customize only the templates you need
 Examples:
 Add Maven profile for deployment
 Add logger declaration
 Customize generated unit tests
 …

 Customize Codegen Languages
 Extend Language class
 Add it to io.swagger.codegen.CodegenConfig
 swagger-codegensrcmainresourcesMETA-
INFservicesio.swagger.codegen.CodegenConfig
 Copy language templates

WADL?
From WADL to Swagger
 Use wadl2java to generate server stub
 BeanValidation: krasa-jaxb-tools
 Activate CXF3 SwaggerFeature
 Use generated Swagger-file
 Will include BeanValidation annotations for
models

Swagger-Codegen – What‘s
next for CXF
 Support for OpenAPI 3.0 (issue 6517)
 Follow/Generate schema references
(and external schema references…)
 And keep them in the generated sources…
 True Polymorphism/inheritance
(currently merged from parents)
 Dynamic merge of new methods for
implementation + tests
 ???

Wrapup
 Generate based on contract
 Swagger-Codegen server stubs
 Extend using code first
 CXF 3 Swagger Feature
 Freeze using contract
 Swagger-Codegen build integration (mvn/gradle/cmd)
 Use your application
 Generate client code (Swagger-Codegen)
 Use in browser (Swagger-UI)
 View/Share as HTML/PDF (Swagger2Markup)
 Customize the code generator

Contribute to the projects
 OpenAPI
 Join the technical developer community
 Swagger-Codegen
 Java / JMustache
 Swagger-UI
 Javascript
 Swagger-Editor
 Javascript
 RepreZen Eclipse KaiZen
 Java
 Swagger2Markup
 Java/Asciidoctor

Thank you for your
attention!
 Demo-Code:
http://github.com/jfiala/swagger-cxf-demo
 Contact:
 @johannes_fiala

Links & Resources
 Swagger Editor
 http://editor.swagger.io/
 RepreZen Eclipse KaiZen Plugin
 https://github.com/RepreZen/KaiZen-OpenAPI-Editor
 Swagger Codegen
 https://github.com/swagger-api/swagger-codegen
 Swagger UI
 https://github.com/swagger-api/swagger-ui
 CXF
 http://cxf.apache.org/

Jcon 2017 How to use Swagger to develop REST applications

More Related Content

What's hot (20)

Similar to Jcon 2017 How to use Swagger to develop REST applications (20)

Recently uploaded (20)

Jcon 2017 How to use Swagger to develop REST applications