Post on 07-Aug-2015
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
Swagger – Extended Code Generation with RuleX
Server Side Code Generator
Test Data Generator
Swagger UI
Define API behavior in more detail with rules
Swagger Editor
Let API consumers browse detailed API behavior
Generate Jax-RS server with validation & simulation based on rules logic
RuleX Code GeneratonGenerate pass and fail test
data based on rules logic
RuleX
RuleX Swagger Editor - Alpha
Gluecon 2015: cliff.faurer(at)nomos-software.com
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
Traditional softwareAPIs / Digital Services
Support – need to support high volume of customers with whom you have little / no contact
Build and deliver – lower value: simpler services that are just expected to work; lower effort: simpler offering, no customization for individual customers
Design – services must be exactly right
API Lifecycle Challenge
New areas of focus in software lifecycle
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
Helps Design
Helps Support
Description language for APIs & with developer tools
Rapid prototyping
Interactive documentation
API Provider
API Consumer
API Lifecycle Challenge
Swagger – helps meet these challenges
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
What is Swagger?
Swagger Specification
Swagger for API
https://github.com/swagger-api/swagger-spec
Uses JSON schema to define API parameters and responses
Swagger Tools
Swagger UI = interactive
documentation
SDK Generator Server Side Code Generator
Code Annotation to Swagger Generator
For language-agnostic descriptions of REST APIs Developer-centric tools for working with swagger
Swagger Editor
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
Example Swagger Description
The paths / operationsPOST customerGET customerPUT (update) customer based on idGET customer based on idDELETE customer based on id
POST paymentMeanetc
The data model for API request parameters and responses
Based on JSON schema
For a ‘telecoms’ customer management API based on TMForum defined API, reference https://www.amkbcloud.com/blog/ for details
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
Swagger UI
Swagger Tools
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
Swagger Editor
Swagger Tools
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
Virtual API
Rapid Prototyping of Virtual API using Swagger Server Generators
Can generate server for:- NodeJS- JAX-RS- Scalatra- Spring-MVC
Swagger Editor
However:
- No JSON syntax validation- No JSON schema validation- No business rules validation- No definition of what the API should
return when it receives a valid request
Swagger Description
Server Side Code Generators
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
Swagger Description
RulesFunctioning API with
- rich diagnostics and
- simulated responses
Virtual API
Rapid Prototyping of Virtual APIs - with server-side logic for validation and simulation
Generates JAX-RS server with:
- JSON syntax validation- JSON schema validation- Validation against rules- Simulated responses
RuleX Server Side Code Generator
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
RuleX Available fromhttp://www.nomos-software.com/
Commercial ‘code generation’ productfrom Nomos Software
RuleX ‘Code Generation’ Product
Swagger Description
Rules
RuleX Server Side Code Generator
Jax-RS server = java readable source code with
- endpoints based on swagger paths
- java class for each type in swagger definitions
- java class for each rule
- rules triggering code
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
Server Generation from Swagger
Basic What isPossible
Possible from Swagger + Rules
Swagger editor JAX-RS Codegen
RuleX Codegen RuleX Codegen
Server with stub endpoints
Dummy responses
JSON syntax validation
Validation against swagger definitions (json schema)
Validiation based on rules
Simulated responses based on rules
Sample (pass and fail) API requests based on rules (not included in Server)
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
Rapid prototyping process – very fast iteration
Immediate regeneration
Virtual API
Swagger UISwagger Description
Rules
EDIT
EDIT
Faster than iteratively updating server-side code as ideas on the design and behaviour of the API develop
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
Rapid Prototyping Benefits
Helps Design
Iterative, agile approach to designing the API
API Consumer plays with virtual API – Designer learns early about user expectations
Swagger UI
Send API request
API User : Designer or Consumer
Receive responses
Virtual API
Try out a demo of a generated virtual API: http://nomos-software.com/blog/swagger-ui-example
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
“Support” Benefits
Rich diagnostics
Improved developer / API Consumer experience
Self-service support : lower cost, and more effective for high volume customers
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
What we do now: parallel documents in .json & .json5 format
Extending Swagger with Rules
Swagger Description
Rules
.json5 or .yaml format
Rules for - validation- simulated responses- test data generation
Rules are written against the definitions in the swagger
.json or .yamlformat
defining API behaviour more
completely
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
Example rulesValidation rules are expressed in OCL from omg.org: - http://clients.nomos-software.com/RuleXOCLUserGuide.html
Simulation and test generation rules are expressed in our proprietary actions language (extension of OCL):- http://clients.nomos-software.com/RuleXActionsUserGuide.html
These types of ‘rules’ are often found in API documentation and appendices, and sometimes … embedded somewhere in the code
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
How rules can add “power” to Swagger tooling
SDK GeneratorServer Side Code Generator
Test Data Generator
Swagger UI
Let API producers define API behavior in more depth
Swagger Editor
Let API consumers browse detailed API behavior
Generate server side validation & simulation
RuleX
Generate pass and fail test data
Generate client side validation
RuleX
RuleX - alpha
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
Swagger Editor for RuleX - Alpha
Edit a rule in the “rule expression editor” pane. Includes syntax checking.
“Rule metadata” pane. Edit information about the rules here : name, error message etc. To edit the rule expression itself, click the link for the rule in the righthand pane and the rule expression is displayed in the rule editor pane above.
View swagger and rules here - also provides means to call the API.
To add / edit a rule expression, click the rule link. The rule is loaded to the “rule expression editor” pane.
Swagger 2.0 pane – edit swagger description here
Generate RuleX jax-RS server and download.
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
• Use swagger plus rules to define API behaviour in more depth
• Can automatically generate server side APIs with simulated behaviour and strong validation for good diagnostics
• Good for API Design, good for API support
Summary
Traditional softwareAPIs / Digital Services
Support
Build and deliver
Design
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
Find out more
Download RuleX Eclipse plugin for swagger from www.nomos-software.com/developers
- take a look at RuleX generated code- send us your comments
Contact us to try out early release of RuleXSwagger Editor
Email cliff.faurer(at)nomos-software.com