Swagger / Quick Start Guide
•
20 j'aime•7,670 vues
This presentation shows main aspects on using Swagger for API developers
Recommandé
Contenu connexe
Tendances
Tendances (20)
Similaire à Swagger / Quick Start Guide
Similaire à Swagger / Quick Start Guide (20)
Plus de Andrii Gakhov
Plus de Andrii Gakhov (20)
Dernier
Dernier (20)
Swagger / Quick Start Guide
- 1. SWAGGER 2.0 Quick Start Guide tech talk @ ferret Andrii Gakhov
- 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. 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. 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. 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. 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
- 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. DEMO API
- 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. 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. 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. 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. 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. YAML http://pastebin.com/B2drjPKt JSON http://pastebin.com/R0EsGyaK FULL SWAGGER DEFINITION Try It here: http://editor.swagger.io/
- 18. STANDALONE DOCUMENTATION WITH SWAGGER UI https://github.com/swagger-api/swagger-ui
- 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. 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
- 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
- 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. Thank you @gakhov Slideshare: www.slideshare.net/gakhov LinkedIn: www.linkedin.com/in/gakhov