nomos software swagger overview

www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware

About Swagger : swagger.io

Swagger is a project used to describe and document RESTful APIs.

Swagger project is open source and sponsored by

Swagger Specification - http://swagger.io/specification/

Swagger Tooling - http://swagger.io/tools/

Swagger Community - http://swagger.io/community/

Slides presented at Swagger Meetup, Dublin Sept 2015, by david.garry(at)nomos-software.com


My Experience with Swagger

• Part of team that used swagger for some telco APIs (Billing Mgmt, Product Order, Customer Mgmt etc)

• Built a code generator that consumes Swagger documents and generates JAX-RS Java servers. http://nomos-software.com/products

• Extended Swagger Editor to allow you to specify how an API should behave when it receives requests. https://github.com/nomos-software/swagger-editor-rulex


Uses JSON schema to define API parameters and responses

For language-agnostic descriptions of REST APIs

Free developer-centric tools for working with Swagger

More on Swagger

API Description Language + Tools


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 customer management API based on TMForum defined API, reference https://www.amkbcloud.com/blog/ for details


API Description Languages

Mainly uses XML Schema

Mainly usesJSON Schema

WADL

Swagger

RAML

API Blueprint

not used much

Sponsored by Smartbear, largest community, lots of tools

Sponsored by Mulesoft

Sponsored by Apiart

API Description Languages - Alternatives


What is the Swagger Specification?

The Swagger specification defines a set of files required to describe an API.

http://swagger.io/specification/

https://github.com/swagger-api/swagger-spec

Describes:

- Format- File Structure- Data types (http://json-schema.org/latest/json-schema-

core.html#anchor8)- Schema


Core Swagger Tools : https://github.com/swagger-api

Generate and Consume Swagger documents built around JAX-RShttps://github.com/swagger-api/swagger-core

Generate documentation and sandbox from Swagger documentshttps://github.com/swagger-api/swagger-ui

Swagger UI

Generate client libraries and server stubs from Swagger documentshttps://github.com/swagger-api/swagger-codegen/tree/develop_2.0

Swagger Codegen

Edit API specifications in YAML inside your browser and to preview documentations in real timehttps://github.com/swagger-api/swagger.io/blob/wordpress/tools/swagger-editor.md

Swagger Editor

Swagger Core


Adjacent Swagger Tools

Javascript library for consuming Swagger-defined APIs from both client and node.js applicationshttps://github.com/swagger-api/swagger-js

Swagger JS

Swagger module for node.js https://github.com/swagger-api/swagger-node

Swagger Node

Expose/invoke Swagger defined APIs over WebSocketshttps://github.com/swagger-api/swagger-socket

Swagger-Socket

Standalone library for parsing Swagger definitions from Javahttps://github.com/swagger-api/swagger-parser

Swagger Parser


Try it out at http://petstore.swagger.io/. On github at https://github.com/swagger-api/swagger-ui

For a more complex example, try http://54.171.250.144/swagger-ui-master/dist/. Instructions and some sample API requests available here http://nomos-software.com/blog/swagger-ui-example

Swagger UI


Play with the editor at : http://editor.swagger.io/#View on github at : https://github.com/swagger-api/swagger-editor

Swagger Editor


Beta tool, not part of swagger project but based on Swagger Editor. APIStudio is connected to Apigee environments (Apigee contributed the swagger editor to the swagger project) : http://apistudio.io/

APIStudio from Apigee


Hosted environment for your swagger : launched by Smartbear to provide Collaboration and Coordination across API Lifecycle

SwaggerHub : swaggerhub.com


SwaggerHub Example


• Design • Code• Virtualize• Test• Document• Deploy• Monitor helps meet these challenges

API Lifecycle Challenge


Design * Swagger EditorCode Swagger Core /

CodegenTest Adjacent ToolsVirtualize Adjacent toolsDocument Swagger-UIDeploy Adjacent toolsMonitor Adjacent tools

* Swagger Editor provides an environment for describing an API as part of the design step. For more general material on designing APIs, see discussions on API First, http://apievangelist.com/2014/08/11/what-is-an-api-first-strategy-adding-some-dimensions-to-this-new-question/, the API Academy material, http://www.apiacademy.co/ (from CA), and http://hello.apiware.io/apidesign

API Lifecycle Challenge with Swagger


RuleXJaxRSServer

Swagger UI

Cloud Container

RuleX Swagger Editor

API Consumer

RuleX Code Generation for APIs

API Designer

RuleX code generation

interacts with

Swagger Descriptionpublish view

RuleX code generation

RuleX Test API Calls

Usage of Swagger at Nomos

More on RuleX Swagger Editor : http://nomos-software.com/blog/rulex-swagger-editorProject on github at https://github.com/nomos-software/swagger-editor-rulex


Free Swagger Tools

APIStudio RuleX

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

Anonymised API calls

Comparison of Server Code Generators


Software Vendor

API Consultancy Services

Our RuleX product supports Swagger

About Nomos Software

Design, Test, Deploy, Document, API Tools Ecosystem etc

Contact: david.garry(at)nomos-software.com

nomos software swagger overview

Technology