APIStrat Workshop @Gluecon 2015:swagger - extended code generation with RuleX

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


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


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


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


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


Swagger UI

Swagger Tools


Swagger Editor

Swagger Tools


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


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


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


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)


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


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


“Support” Benefits

Rich diagnostics

Improved developer / API Consumer experience

Self-service support : lower cost, and more effective for high volume customers


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


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


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


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.


• 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


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

APIStrat Workshop @Gluecon 2015:swagger - extended code generation with RuleX

Technology

Transcript of APIStrat Workshop @Gluecon 2015:swagger - extended code generation with RuleX