Swagger APIs for Humans and Robots (Gluecon)

5,495 views

Published on

Presentation to Gluecon 2014 about Swagger for API development and adoption of services. Reverb also announced the Swagger 2.0 Working Group, with Apigee as a founding member

Published in: Technology
0 Comments
7 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
5,495
On SlideShare
0
From Embeds
0
Number of Embeds
1,120
Actions
Shares
0
Downloads
67
Comments
0
Likes
7
Embeds 0
No embeds

No notes for slide
  • Services, internal or external, are the new unit of software
  • How modules are documented varies wildly by language, technology
  • Swagger APIs for Humans and Robots (Gluecon)

    1. 1. Swagger APIs for Humans (and Robots) @fehguy
    2. 2. Swagger Philosophy
    3. 3. Swagger Philosophy Service documentation sucks typically
    4. 4. Swagger Philosophy • Communicating is too much work – Users don’t want to write YOUR SDK – If you’re good at Ruby, you suck at GO • Consumers need a contract – Service logic doesn’t belong in the SDK • Services are plumbing – We shouldn’t all be plumbers – Business logic is your business
    5. 5. Swagger Philosophy • Solved by machine-readable, discoverable API contract • Should speed up, not slow down development process • External services/proxies not required
    6. 6. What is Swagger? • An interface to your service – Described in JSON • It is a contract to your service • Enables “bigotry-free” restful design with emphasis on getting things done – Many ways to delete a Pet
    7. 7. How does it work? • Discoverable at runtime, not compile-time • It’s just JSON • No server integration required – You can describe an API that’s not even yours – Deploy anywhere! Put it on github! – Swagger is JUST a way to describe an API
    8. 8. But Why? • Machine-readable contract – Description of *everything* the server can do – Server-controlled documentation – Server/language/platform/deployment agnostic • Documentation, code generation, client generation – Like Headers for C, Interfaces for Java
    9. 9. Swagger UI
    10. 10. Client SDKs • Your consumers want to use your service – How they want – Not write your software
    11. 11. How do you add Swagger? • Static Files – Manually crafted JSON • Heuristics – Traffic inspection • Code inspection – Code comments, static annotations • Runtime generation It’s just JSON!
    12. 12. Client Generation https://github.com/wordnik/swagger-codegen • Templates can be generated your way • Typed and untyped languages Groovy Java Android async-scala C# Flash Objective C PHP Python Python 3 Ruby Scala
    13. 13. Client Generation • Requires a proper API definition • Type info, parameters, input/output models • Protocol, path, authentication • Templates are a starting point – Clone, configure, put in workflow
    14. 14. Client Generation • Configuration Script – Packages – Imports – Type Mapping – Packaging info • Group ID, Artifact ID, version • Templates – Boilerplate code
    15. 15. Client Generation • Codegen for client generation
    16. 16. Static Doc Generation • Codegen !== client generation • Templates are generic
    17. 17. Static Doc Generation
    18. 18. Server Generation • Specs can generate servers
    19. 19. How do you write Software? • Code first? • Design first? • Hybrid? One size does NOT fit all
    20. 20. Top Down vs. Bottom-up • Design-first is not this (anymore)
    21. 21. Top Down • GUI vs. XML? The world chose GUI! • GUI vs. JSON? • GUI vs. YAML?
    22. 22. Top Down? XML: 453 Lines JSON: 512 Lines YAML: 400 Lines It’s not about the line count!
    23. 23. Introducing Swagger Editor!
    24. 24. Evolution of Swagger • Swagger Editor – Angular, Ace – OSS, Apache 2.0 • Thank you Community! – 500k downloads of java framework alone – ~10k production deployments – 4k stars, 1600 forks – Big & Small
    25. 25. Swagger 2.0 Working Group • Give your input on Swagger 2.0 Specification • Coming this Summer • More info: – http://swagger.wordnik.com • Join the evolution – https://github.com/wordnik/swagger-spec
    26. 26. Swagger has a Community • Server integrations JAX-RS (java) Scalatra (scala) Spring MVC (java) Spray (scala) Composer (PHP) django (python) Flask (python) Go Maven (JAX-RS) ServiceStack (.net) Doctrine (PHP) Express (JS) Restler (PHP) Hapi (JS) Clojure
    27. 27. Swagger is FOSS • Apache 2 License https://github.com/wordnik/swagger-spec https://github.com/wordnik/swagger-core https://github.com/wordnik/swagger-codegen https://github.com/wordnik/swagger-editor https://github.com/wordnik/swagger-ui https://github.com/wordnik/swagger-node-express https://github.com/scalatra/scalatra
    28. 28. Where to go for help Google Groups • https://groups.google.com/forum/#!forum/s wagger-swaggersocket IRC • irc.freenode.net Email • apiteam@wordnik.com

    ×