Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
SWAGGER 2.0
Quick Start Guide
tech talk @ ferret
Andrii Gakhov
WHAT IS SWAGGER?
• The goal of Swagger™ is to define a standard, language-agnostic
interface to REST APIs which allows both...
SWAGGER ECOSYSTEM
• Swagger Editor

edit API specifications inYAML inside browser and preview
documentations in real time.
...
USAGE PATTERNS FOR API PROVIDERS
Swagger
Editor
Swagger
Definition
Swagger
Codegen
Swagger
UI
API
Swagger Editor
Swagger
De...
SWAGGER SPECIFICATION
• The Swagger representation of the API is made of a single file
swagger.json (but can refer to other...
SWAGGER OBJECT
info
API metadata
paths
available paths and operations
definitions
data types produced and consumed by opera...
SWAGGER EDITOR EXAMPLE
SWAGGER UI EXAMPLE
SWAGGER UI EXAMPLE
COMMUNITY-DRIVEN LANGUAGE
INTEGRATIONS
• Clojure
• ColdFusion / CFML
• Eiffel
• Go
• Groovy
• Java
• JavaScript
• Node.js
...
DEMO API
UNFORMAL SPECIFICATION
• We want to design DEMO API that can provide access to our database of
articles
• Every article in...
SWAGGER DEFINITION METADATA
"swagger": "2.0",
"info": {
"title": "DEMO API",
"description": "Demonstration for techtalk @ ...
SWAGGER DEFINITION FOR OBJECTS
"Article": {
"properties": {
"id": {
"type": "string",
"description": "Unique identifier.”
}...
SWAGGER DEFINITION FOR PATHS
"/articles": {
"get": {
"summary": "Get Articles”,
“operationId”:“getArticles”,
"parameters":...
SWAGGER DEFINITION FOR PATHS
"/article/{id}/authors": {
"get": {
"summary": "Get Authors”,
"operationId": "getAuthorByArti...
YAML http://pastebin.com/B2drjPKt
JSON http://pastebin.com/R0EsGyaK
FULL SWAGGER DEFINITION
Try It here: http://editor.swa...
STANDALONE DOCUMENTATION
WITH SWAGGER UI
https://github.com/swagger-api/swagger-ui
SWAGGER-UI
• a part of the Swagger project
• a dependency-free collection of HTML, JS and CSS assets that
dynamically gene...
SWAGGER UI SETUP
• Make swagger.json and all external $ref accessible via internet
• Setup CORS settings and (optionally) ...
DOCUMENTATION EXAMPLE
TESTING API
WITH PYSWAGGER
https://github.com/mission-liao/pyswagger
PYSWAGGER
• a python client for Swagger enabled REST API
• supports Swagger 1.2, 2.0 on python 2.6, 2.7, 3.3, 3.4
• tries ...
PYSWAGGER COMPONENTS
PYSWAGGER EXAMPLE
from pyswagger import SwaggerApp, SwaggerSecurity
from pyswagger.contrib.client.requests import Client
#...
Thank you
@gakhov
Slideshare: www.slideshare.net/gakhov
LinkedIn: www.linkedin.com/in/gakhov
Upcoming SlideShare
Loading in …5
×

Swagger / Quick Start Guide

6,114 views

Published on

This presentation shows main aspects on using Swagger for API developers

Published in: Software

Swagger / Quick Start Guide

  1. 1. SWAGGER 2.0 Quick Start Guide tech talk @ ferret Andrii Gakhov
  2. 2. WHAT IS SWAGGER? • The goal of Swagger™ is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. • Swagger is a formal specification surrounded by a large ecosystem of tools
  3. 3. SWAGGER ECOSYSTEM • Swagger Editor
 edit API specifications inYAML inside browser and preview documentations in real time. • Swagger Codegen
 allows generation of both client libraries and server stubs from a Swagger definition. • Swagger UI
 dependency-free collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation from a Swagger- compliant API http://swagger.io/tools/
  4. 4. USAGE PATTERNS FOR API PROVIDERS Swagger Editor Swagger Definition Swagger Codegen Swagger UI API Swagger Editor Swagger Definition Swagger Codegen Swagger UI API API Swagger-Core JAX-RS Automatic generation top-down approach bottom-up approach
  5. 5. SWAGGER SPECIFICATION • The Swagger representation of the API is made of a single file swagger.json (but can refer to other resources) • Represented as JSON, butYAML can be used • All field names are case sensitive • Primitive data types in the Swagger Specification are based on the types supported by the JSON-Schema Draft 4. • Models are described using the Schema Object which is a subset of JSON Schema Draft 4. https://github.com/swagger-api/swagger-spec/
  6. 6. SWAGGER OBJECT info API metadata paths available paths and operations definitions data types produced and consumed by operations parameters parameters that can be used across operations responses responses that can be used across operations securityDefinitions security scheme definitions security alternative security schemes that can be used tags list of tags with additional metadata externalDocs additional external documentation
  7. 7. SWAGGER EDITOR EXAMPLE
  8. 8. SWAGGER UI EXAMPLE
  9. 9. SWAGGER UI EXAMPLE
  10. 10. COMMUNITY-DRIVEN LANGUAGE INTEGRATIONS • Clojure • ColdFusion / CFML • Eiffel • Go • Groovy • Java • JavaScript • Node.js • Perl • PHP • Python • Ruby • Scala https://github.com/swagger-api/swagger-spec#additional-libraries
  11. 11. DEMO API
  12. 12. UNFORMAL SPECIFICATION • We want to design DEMO API that can provide access to our database of articles • Every article in the database has a list of authors, so internally we have 2 main data objects:Article and Author • All responses from our API should be made in JSON • We want to able: 1. get all articles
 GET /v1/articles 2. get all authors from the particular article
 GET /v1/article/{id}/authors
  13. 13. SWAGGER DEFINITION METADATA "swagger": "2.0", "info": { "title": "DEMO API", "description": "Demonstration for techtalk @ ferret", "version": "1.0.0" }, "host": "api.demo.berlin", "schemes": [ "http", "https" ], "basePath":“/v1", “consumes”: [ “application/json” ], "produces": [ "application/json" ],
  14. 14. SWAGGER DEFINITION FOR OBJECTS "Article": { "properties": { "id": { "type": "string", "description": "Unique identifier.” }, "title": { "type": "string", "description": "Title of the article." }, "text": { "type": "string", "description": "Text of the article." }, "authors": { "type": "array", "items": { "$ref": "#/definitions/Author" } … "Author": { "properties": { "id": { "type":“string”, “description”:“Unique identifier.” }, "name": { "type": "string", “description”:“Name of the author.” }, "email": { "type": "string",, “description”:“Author’s email.” } … Because we want to return collections of such objects, we need to define them in Swagger too!!! Articles and Authors
  15. 15. SWAGGER DEFINITION FOR PATHS "/articles": { "get": { "summary": "Get Articles”, “operationId”:“getArticles”, "parameters": { "name": "size", "in": "query", "required": false, "default": 10, "maximum": 100, "type": "number", "format": "int32" }, { "name": "offset", "in": "query", "required": false, "default": 1, "type": "number", "format": "int32" }], "tags": [ "Articles" ], "responses": { "200": { "description": "An array of articles", "schema": { "$ref": "#/definitions/Articles" } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } }
  16. 16. SWAGGER DEFINITION FOR PATHS "/article/{id}/authors": { "get": { "summary": "Get Authors”, "operationId": "getAuthorByArticleID", "description": "The Authors endpoint returns all authors for the specific article identified by {id}”, "parameters": [ { "name": "id", "in": "path", "description": "Id of the Article", "required": true, "type": "string" } ], "tags": [ “Articles”, "Authors" ], "responses": { "200": { "description": "An array of authors", "schema": { "$ref": "#/definitions/Authors" } }, "404": { "description": "Article Not Found", "schema": { "$ref": "#/definitions/Error" } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } …
  17. 17. YAML http://pastebin.com/B2drjPKt JSON http://pastebin.com/R0EsGyaK FULL SWAGGER DEFINITION Try It here: http://editor.swagger.io/
  18. 18. STANDALONE DOCUMENTATION WITH SWAGGER UI https://github.com/swagger-api/swagger-ui
  19. 19. SWAGGER-UI • a part of the Swagger project • a dependency-free collection of HTML, JS and CSS assets that dynamically generate documentation • can host in any server environment • easy to install and configure • customizable and supports easy localization and translation • supports invocation of all HTTP methods (GET, PUT, POST, DELETE, PATCH, OPTIONS)
  20. 20. SWAGGER UI SETUP • Make swagger.json and all external $ref accessible via internet • Setup CORS settings and (optionally) api_key to access them add_header 'Access-Control-Allow-Origin' '*'; add_header 'Access-Control-Allow-Credentials' 'true'; add_header 'Access-Control-Allow-Methods' 'GET, POST, DELETE, PUT, PATCH, OPTIONS'; add_header 'Access-Control-Allow-Headers' 'Content-Type, api_key,Authorization'; • Download Swagger UI to the server e.g. as swagger-ui • Make swagger-ui/dist folder accessible via browser (e.g. configure webserver) • Just run open it in the browser
  21. 21. DOCUMENTATION EXAMPLE
  22. 22. TESTING API WITH PYSWAGGER https://github.com/mission-liao/pyswagger
  23. 23. PYSWAGGER • a python client for Swagger enabled REST API • supports Swagger 1.2, 2.0 on python 2.6, 2.7, 3.3, 3.4 • tries hard to fully supports Swagger Spec in all aspects • supports JSON andYAML • provides client implementation based on various http clients in python • easy to unittest API • easy to validate API definition according to spec
  24. 24. PYSWAGGER COMPONENTS
  25. 25. PYSWAGGER EXAMPLE from pyswagger import SwaggerApp, SwaggerSecurity from pyswagger.contrib.client.requests import Client # create application from the Swagger spec app = SwaggerApp._create_(‘https://example.com/swagger.json’) # specify authorization credentials auth = SwaggerSecurity(app) auth.update_with('api_key', '12312312312312312313q') # create client to access API client = Client(auth) # access an Operation object via SwaggerApp.op when operationId is defined authors = client.request(app.op['getAuthorsByArticleID'](id=1)).data assert len(authors.items) == authors.total articles = client.request(app.op[‘getArticles’]).data assert len(articles.items) <= articles.total
  26. 26. Thank you @gakhov Slideshare: www.slideshare.net/gakhov LinkedIn: www.linkedin.com/in/gakhov

×