Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Introduction to Swagger

Introduction to Swagger

Talk at the WebAPI Meetup in Hamburg 2016

Nils Löwe

March 15, 2016
Tweet

More Decks by Nils Löwe

Other Decks in Programming

Transcript

  1. Introduction to Swagger 15.03.16 / Web API Meetup / Wer

    liefert Was? @NilsLoewe
  2. What is Swagger?

  3. Swagger is a representation for REST APIs: Interactive documentation Client

    SDK generation Discoverability Supporting many programming languages and environments 100% Open Source
  4. What's Open Source in this case?

  5. 2011-08-10: First release of the Swagger Speci cation To bring

    the “good parts” of REST, SOAP, Web Services and RPC into a simple, easy to understand format.
  6. 2014-09-08: Release of Swagger 2.0 Swagger tools are downloaded close

    to 15,000 times per day. 2000 known open-source repositories for Swagger tools First-class support across all major API management platforms.
  7. 2016-01-01 The Open API Initiative Part of the Linux Foundation

    Founding partners: Google, Microsoft, IBM, 3Scale, Apigee, CapitalOne, Intuit, PayPal, and Restlet. openapis.org
  8. None
  9. How to use Swagger?

  10. New API: Top-Down Use the Swagger Editor to create your

    Swagger de nition Use the Swagger Codegen tools to generate server implementation
  11. Existing API: Bottom-Up You have an existing REST API You

    want to create a Swagger de nition Option A: Create the de nition manually using the Swagger Editor Option B: Integrate the framework into your Code and get the Swagger de nition generated automatically
  12. Build a new client for a Swagger-described API Use the

    online version of the Swagger UI to explore the API (given that you have a URL to the APIs Swagger de nition) Use Swagger Codegen to generate the client library
  13. Swagger Tools

  14. Swagger-Codegen Generating client libraries and server stubs from a Swagger

    de nition Required: Java 7, Apache maven > 3.0.3 Available via homebrew, Docker, Vagrant, ... https://github.com/swagger-api/swagger-codegen
  15. Swagger-UI A dependency-free collection of HTML, Javascript, and CSS assets

    that dynamically generate beautiful documentation and sandbox from a Swagger-compliant API Works in all common browsers (Chrome, Safari, Firefox, IE8++) Download from https://github.com/swagger-api/swagger- ui
  16. Available Integrations Open Source Implementations available for Clojure, Coldfusion, D,

    Eiffel, Erlang, Go, Groovy, Haskell, Java, Javascript, TypeScript, .NET, Node.JS, Perl, Python, Php, Ruby, Scala Commercial Implementations available for http://swagger.io/commercial-tools/
  17. Describing APIs with Swagger

  18. A 'hello world' API s w a g g e

    r : " 2 . 0 " i n f o : v e r s i o n : " 1 . 0 " t i t l e : " H e l l o W o r l d A P I " p a t h s : / h e l l o / { u s e r } : g e t : d e s c r i p t i o n : R e t u r n s a g r e e t i n g t o t h e u s e r ! p a r a m e t e r s : ­ n a m e : u s e r i n : p a t h t y p e : s t r i n g r e q u i r e d : t r u e d e s c r i p t i o n : T h e n a m e o f t h e u s e r t o g r e e t . r e s p o n s e s : 2 0 0 : d e s c r i p t i o n : R e t u r n s t h e g r e e t i n g . s c h e m a :
  19. API Info t i t l e s t r

    i n g R e q u i r e d . T h e t i t l e o f t h e a p p l i c a t i o n . d e s c r i p t i o n s t r i n g A s h o r t d e s c r i p t i o n o f t h e a p p l i c a t i o n . t e r m s O f S e r v i c e s t r i n g T h e T e r m s o f S e r v i c e f o r t h e A P I . c o n t a c t O b j e c t T h e c o n t a c t i n f o r m a t i o n f o r t h e e x p o s e d A P I . l i c e n s e O b j e c t T h e l i c e n s e i n f o r m a t i o n f o r t h e e x p o s e d A P I . v e r s i o n s t r i n g R e q u i r e d P r o v i d e s t h e v e r s i o n o f t h e a p p l i c a t i o n A P I
  20. Data types i n t e g e r i

    n t e g e r i n t 3 2 s i g n e d 3 2 b i t s l o n g i n t e g e r i n t 6 4 s i g n e d 6 4 b i t s f l o a t n u m b e r f l o a t d o u b l e n u m b e r d o u b l e s t r i n g s t r i n g b y t e s t r i n g b y t e b a s e 6 4 e n c o d e d c h a r a c t e r s b i n a r y s t r i n g b i n a r y a n y s e q u e n c e o f o c t e t s b o o l e a n b o o l e a n d a t e s t r i n g d a t e A s d e f i n e d b y f u l l ­ d a t e ­ R F C 3 3 3 9 d a t e T i m e s t r i n g d a t e ­ t i m e A s d e f i n e d b y d a t e ­ t i m e ­ R F C 3 3 3 9 p a s s w o r d s t r i n g p a s s w o r d U s e d t o h i n t U I s t h e i n p u t n e e d s t o b e o b s c u r e d .
  21. Schemes s w a g g e r s t

    r i n g R e q u i r e d . S p e c i f i e s t h e S w a g g e r S p e c i f i c a t i o n v e r s i o n i n f o I n f o O b j e c t R e q u i r e d . P r o v i d e s m e t a d a t a a b o u t t h e A P I h o s t s t r i n g T h e h o s t ( n a m e o r i p ) s e r v i n g t h e A P I b a s e P a t h s t r i n g T h e b a s e p a t h o n w h i c h t h e A P I i s s e r v e d , r e l a t i v e t o t h e s c h e m e s [ s t r i n g ] T h e t r a n s f e r p r o t o c o l : " h t t p " , " h t t p s " , " w s " , " w s s " c o n s u m e s [ s t r i n g ] A l i s t o f M I M E t y p e s t h e A P I s c a n c o n s u m e p r o d u c e s [ s t r i n g ] A l i s t o f M I M E t y p e s t h e A P I s c a n p r o d u c e p a t h s P a t h s O b j e c t R e q u i r e d . T h e a v a i l a b l e p a t h s a n d o p e r a t i o n s f o r . . . h t t p : / / s w a g g e r . i o / s p e c i f i c a t i o n /
  22. Demo Time! http://petstore.swagger.io/

  23. Thank you! https://slides.nils-loewe.de/ @NilsLoewe