How to generate a REST CXF3 application from Swagger ApacheConEU 2016
- 1. How to Generate a REST CXF3 Application from a Swagger-Contract Johannes Fiala, Developer
- 2. Agenda • Generate based on contract • Extend using code first • Freeze the contract • Use the REST API • Generate client code (Java/Javascript) • Access with a browser using a UI • View/Share as HTML/PDF • Customize the code generator
- 3. Toolchain • Apache CXF 3 • + SwaggerFeature • + Spring configuration • + Spring Boot integration (start/tests) • Swagger-Tools • Swagger-Editor • Swagger-Codegen • Swagger-UI • Swagger2Markup
- 4. Contract first, then code, then contract
- 6. About me… • Spring REST / Swagger-Springfox • Added BeanValidation support • Swagger-Codegen • Created Javascript client • Add BeanValidation support for Java • Improved CXF server (generate complete server) • Created CXF client • Swagger2Markup • Added BeanValidation support
- 7. Contract • 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 • Next version 3.0 • Others: Blueprint, RAML, …
- 8. Open API / Swagger • A language-agnostic interface to REST APIs • allows to discover and understand the capabilities of a service • Supported Formats: JSON/YAML https://github.com/OAI/OpenAPI-Specification
- 9. Contract editors • Swagger Editor • by SmartBear • Eclipse SwagEdit • By RepreZen API Studio • Commercial Tools: • Restlet Studio • RepreZen API Studio
- 11. Swagger-Editor • By SmartBear • Javascript application • Run locally using npm • Edit Json / Yaml format • Generate server • Generate client • Import using URL / copy/paste https://github.com/swagger-api/swagger-editor
- 12. Generate the server stub Swagger-Codegen • by SmartBear (Apache License) • Version 2.2.0 • Java program • Mustache templating • Generates server + client code • 32 Supported languages: Java, C#, Javascript, Dart, Groovy, JaxRS, NodeJS, Objective-C, Perl, PHP, Python, Ruby, Scala, … https://github.com/swagger-api/swagger-codegen
- 13. Generate the server stub Swagger-Codegen • Supported server stubs for Java: • Java JAX RS • 2.0 spec • Jersey • CXF • Resteasy • Spring MVC • Spring Boot
- 14. CXF server stub Features • Scheduled for version 2.2.2 • 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 • Tests • Run using Spring Integrationtests using random ports • Currently no update/merge for new methods …
- 15. Swagger-Codegen CLI • io.swagger.codegen.Codegen -i hello_world.json -l jaxrs-cxf -o c:hello_world_project -c hello_world_config.json
- 17. Demo • Create hello world service • Generate CXF server stub (with Spring support enabled) • Run using Spring Boot • Run Junit-Tests • Deploy to application server (Jboss EAP 7)
- 18. 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)
- 19. 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
- 20. Swagger-Codegen CLI language options for cxf
- 21. Demo • Re-Generate with more options • BeanValidation • Gzip • Logging
- 22. Further development life cycle • Extend the API • code first • Use the API • Frontend development • Finalize: Freeze the contract
- 23. Further development life cycle Contract Generate Code Add/Modify Code
- 24. Extend the application • Modify your API: • Add new services (use JAXRS-annotations) • Use Swagger annotations • Use BeanValidation annotations • Generated Swagger spec gets updated automatically
- 25. Extend the application Swagger annotations • Service: • @Api – activate Swagger for api • Operations: • @ApiOperation - description • @ApiResponse – error codes + return types • Model: • @ApiModel - description • @ApiModelProperty - description
- 26. Freeze your API: contract • Use the updated contract • Generate interfaces/models • Prevent accidential changes of the API • Integrate in build job (Maven / Gradle) • Will generate to target/generated-sources/swagger by default • Use .swagger-codegen-ignore file to protect files from updates • Tests are always protected • https://github.com/swagger-api/swagger- codegen/tree/master/modules/swagger-codegen-maven-plugin
- 27. Freeze your API: contract
- 28. Demo • Extend hello world service (+ BeanValidation) • Access updated specs • Swagger spec • WADL • Freeze the contract
- 29. Spring Boot Hot-Deploy – Spring Loaded • Allows hot deploy • for adding new methods etc. • Add JVM parameters: • -javaagent:/path_to_spring-loaded/springloaded-1.2.5.RELEASE.jar – noverify • Used by Grails • More Info: https://github.com/spring-projects/spring-loaded
- 30. Use your API Generate client stubs • Swagger-Codegen Access your API using a browser • Swagger-UI Generate HTML/PDF documentation Swagger2Markup
- 31. Swagger-Codegen • Server + Client code stub generator • Integration options • Java application • Maven • Gradle • https://github.com/swagger-api/swagger-codegen
- 32. Why generate client code? • No more manual api calls • Ensure consistency of your client code with the API! • 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!
- 33. 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 as Web-Jar https://github.com/swagger-api/swagger-ui
- 34. Swagger-UI
- 35. Swagger2Markup • By Robert Winkler (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
- 37. Demo • Client stub generator: • Java • Javascript • Swagger-UI • Swagger2Markup
- 38. Migration – Ensure portability • Keep method signatures clean • Use JaxRS 2 Exceptions • Use JaxRS Response only if necessary • Keep framework-specific configuration separately
- 39. Customize the generator • Generator implemented in Java (one class for each language) • Mustache-files • api.mustache • apiServiceImpl.mustache • pojo.mustache • api_test.mustache • … • Jmustache: • https://github.com/samskivert/jmustache
- 40. Customize the generator • 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 • …
- 41. Customize the generator • Customize Codegen Languages • Extend Language class • Add it to io.swagger.codegen.CodegenConfig • swagger-codegensrcmainresourcesMETA- INFservicesio.swagger.codegen.CodegenConfig • Copy language templates • Also see "Building your own Templates" • https://github.com/swagger-api/swagger-codegen/wiki/Building-your-own- Templates
- 42. Demo • Customize the generator • E.g. custom pom.xml file for deployment • Swagger-Codegen project structure
- 43. WADL Swagger • Use wadl2java to generate server stub • BeanValidation: krasa-jaxb-tools • Activate CXF3 SwaggerFeature • Use generated Swagger-file • Will include BeanValidation annotations for models • You can use both WADL first + auto-generate Swagger contract
- 44. 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
- 45. Contribute to the projects • Swagger-Codegen • Java / JMustache • Swagger-UI • Javascript • Swagger-Editor • Javascript • Swagger2Markup • Java/Asciidoctor
- 46. Links & Resources • Swagger Editor • http://editor.swagger.io/ • Swagger Codegen • https://github.com/swagger-api/swagger-codegen • Swagger UI • https://github.com/swagger-api/swagger-ui • CXF • http://cxf.apache.org/
- 47. Thank you for your attention! • Demo-Code: http://github.com/jfiala/swagger-cxf-demo • Contact: • @johannes_fiala