Introduction to Swagger

Talk at the WebAPI Meetup in Hamburg 2016

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
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