Embed Size (px)
Citation preview
The Latest and Greatest
James Higginbotham @launchany
SWAGGER – OVERVIEW
Swagger is a simple yet powerful representa<on of your RESTful API.
Drives API Documenta>on
Without Swagger Defini>on
With Swagger Defini>on
Swagger Structure -‐ Info
Swagger Structure -‐ Paths
Swagger Structure -‐ Security
Swagger Structure – Security Types
Swagger Structure -‐ Defini>ons
Swagger Data Types
Swagger is much bigger than Swagger-‐UI
Swagger Ecosystem
Beyond Interac>ve Docs
Beyond Defini>on: Visualiza>on
Swagger.ed
hMps://github.com/chefArchitect/apispots-‐browser-‐swaggered
Swagger 2.0
u Released last year u Evolve the JSON syntax u Add support for human-‐friendly format u Vendor extensions support
From Reverb to SmartBear
Community Contribu>ons Growing!
New: Community-‐Driven Website
u New website underway – hMp://swagger.io – Github driven – Pages have a “View Source on Github” link – For the community, BY the community – Feel free to contribute content
June 6 Release
u SmartBear tools now have 2.0 support throughout u Swagger JS/UI
– Now upgrade older versions of Swagger 2.0 before processing – Major rewrites of the underlying libraries of these projects
u Core and Codegen – Completely rewriMen in Java (used to be Scala) – BeMer extension mechanism to allow for core customiza>ons – Codegen has new templates (Swic, Perl, updated JAX-‐RS)
u Governance – Crea>ng an open governance model for the spec – Will involve other companies and individuals – S>ll figuring out the exact model (before the end of June)
SWAGGER FOR A DESIGN-‐FIRST API
Design First API Approach
Design First API Lifecycle
u Design the API contract u Mock the API for valida>on/collabora>on u Test for compliance/completeness u Build the implementa>on u Deploy u Manage
Fast feedback loops, collabora>ve development
Swagger Support for Design-‐First
u Swagger always top-‐down capable u However, tooling focused on boMom-‐up u History of fragmented tool ecosystem
Introducing Swagger Editor
YAML for the Human
swagger: '2.0' info: version: 1.0.0 >tle: A simple API paths: /: get: responses: 200: descrip>on: OK
JSON for the Tools { "swagger": "2.0", "info": { "version": "1.0.0", ">tle": "A simple API" }, "paths": { "/": { "get": { "responses": { "200": { "descrip>on": "OK" } } } } } }
Swagger Tools: Documenta>on
Swagger Editor: Design your API using simple YAML format, preview. Requires the Node.js app.
Swagger UI:
Display your documenta>on using sta>c HTML and client-‐side
Javascript. No Node.js required.
Swagger Tools: Code Genera>on
Swagger-‐Based Tes>ng
SoapUI: Import and generate tests using SmartBear’s SoapUI tool.
Runscope: Import Swagger and generate run>me tests using Runscope.
Op>on 1: Hosted
u Editor hMp://editor.swagger.io/
u Generators w/ API hMp://generator.swagger.io/
Op>on 2: Install and Customize
hMps://github.com/swagger-‐api/swagger-‐generator
hMps://github.com/swagger-‐api/swagger-‐editor
Editor Extensions
Swagger Editor Callbacks: Callbacks for integra>ng with design/deploy workflows.
Swagger Editor Storage: Backend support using GET and PUT for retrieving and saving YAML defini>ons.
How to Get Started with Swagger
u Use the Swagger Editor to view samples u In parallel, read the Swagger 2.0 Spec to understand samples in-‐depth
u Reverse-‐engineer exis>ng API or third-‐party API into Swagger
u Publish using Swagger-‐UI u Try one of the client code generators (some beMer than others)
