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
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
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
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
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
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 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
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
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
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
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
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
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
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
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
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
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
Play with the editor at : http://editor.swagger.io/#View on github at : https://github.com/swagger-api/swagger-editor
Swagger Editor
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
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
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
Hosted environment for your swagger : launched by Smartbear to provide Collaboration and Coordination across API Lifecycle
SwaggerHub : swaggerhub.com
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
SwaggerHub Example
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
• Design • Code• Virtualize• Test• Document• Deploy• Monitor helps meet these challenges
API Lifecycle Challenge
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
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
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
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
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
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
www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware
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