Introduction to Swagger

Introduction to Swagger

Talk at the WebAPI Meetup in Hamburg 2016

3568131865e186d04045fe7738f89782?s=128

Nils Löwe

March 15, 2016
Tweet

Transcript

  1. 3.

    Swagger is a representation for REST APIs: Interactive documentation Client

    SDK generation Discoverability Supporting many programming languages and environments 100% Open Source
  2. 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.
  3. 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.
  4. 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
  5. 8.
  6. 10.

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

    Swagger de nition Use the Swagger Codegen tools to generate server implementation
  7. 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
  8. 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
  9. 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
  10. 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
  11. 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/
  12. 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 :
  13. 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
  14. 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 .
  15. 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 /