Se ha denunciado esta presentación.
Utilizamos tu perfil de LinkedIn y tus datos de actividad para personalizar los anuncios y mostrarte publicidad más relevante. Puedes cambiar tus preferencias de publicidad en cualquier momento.

Swagger - make your API accessible

15.033 visualizaciones

Publicado el

Presented at http://devcon-oct13.events.co.il/

Publicado en: Tecnología, Empresariales
  • Sé el primero en comentar

Swagger - make your API accessible

  1. 1. Swagger Make your API accessible Victor Trakhtenberg victortr75@gmail.com @victortr75
  2. 2. Personal My name is Victor Almost 15 years of software development Chief Architect @
  3. 3. Architecture SOA APIs https://twitter.com/dcorpa
  4. 4. Architecture APIs are for humans Documentation http://www.infoq.com/resource/presentations/API-Humans/en/slides/sl23.jpg
  5. 5. Documentation
  6. 6. Documentation • No standard • Ad-hoc attributes • Managed manually • Not up to date • ….. http://www.imagineyourreality.com/business-coaching/documentation.html
  7. 7. API Listing
  8. 8. API Operations
  9. 9. API parameters and return types
  10. 10. Swagger is… • producing • consuming • visualizing RESTful APIs A framework for • describing • documenting RESTful APIs A specification for Technology Methodology
  11. 11. The Swagger Specification It’s a spec! • JSON to specify metadata • JSON to specify API structure • JSON schema for the model specification • Machine readable • Language agnostic
  12. 12. Agenda • Introduction • Deep Dive • The technology • Swagger is not • Alternatives • Dev process • Deployment process • References
  13. 13. Deep Dive
  14. 14. Swagger - API Listing
  15. 15. Swagger - API Listing - JSON
  16. 16. Swagger – API Listing - Annotations
  17. 17. Swagger - API Details
  18. 18. Swagger – Test the API
  19. 19. Swagger - API Details - JSON
  20. 20. Swagger – API Details - Annotations
  21. 21. The Technology
  22. 22. Reverb - Wordnik Atmosphere – Scalatra – JSON4S
  23. 23. The Technology – Scala based • swagger-core • swagger-codegen • swagger-ui
  24. 24. Server side integrations • Django • Node.js • JAX-RS • RESTEasy • Grails • Play 2 • Scalatra • go-restful • SpringMVC • ServiceStack .net/MONO • Swagger-PHP • Symphony 2 • Grape-swagger for Ruby • Octohipster for Clojure • More…
  25. 25. Client code generation • Java • Scala • Groovy • Clojure • Python • Ruby • ObjectiveC • C# • PHP • Javascript • Custom • Uses {{mustache}} templates
  26. 26. Swagger is not
  27. 27. • Does not support multiple API versions • Does not tell how to write the API –Delete an object by HTTP DELETE or via HTTP GET with query param • Is not trying to solve all problems for all APIs
  28. 28. Alternatives
  29. 29. • SOAP/WSDL – http://www.w3.org/TR/wsdl • WADL – http://en.wikipedia.org/wiki/Web_Application_Descriptio n_Language • Mashery IO-Docs – http://www.mashery.com/product/io-docs – https://github.com/mashery/iodocs • http://apiary.io/ • Homegrown
  30. 30. Dev Process
  31. 31. API development approaches API specification first –Write the JSON spec –Generate the API stubs –Implement the APIs –Publish
  32. 32. API development approaches API implementation first –Implement the API –Put the annotations in place
  33. 33. Deployment Process
  34. 34. Dev/Test environment Annotate the APIs Make swagger UI accessible from the application itself
  35. 35. Dev/Test environment View the documentation locally Test the APIs using swagger UI
  36. 36. Dev/Test environment Generate internal clients based on swagger specification
  37. 37. Production environment Make swagger UI NOT accessible from the application itself
  38. 38. Production environment Automatically generate external swagger static resources
  39. 39. Production environment Deploy on dedicated web server Synchronize the documentation
  40. 40. Production environment Generate external clients based on swagger specification
  41. 41. References • Swagger home: – https://developers.helloreverb.com/swagger/ • Swagger specification – https://github.com/wordnik/swagger-core/wiki • Swagger Demo – http://petstore.swagger.wordnik.com/ • Wordnik APIs – http://developer.wordnik.com/docs.html#!/account
  42. 42. Make your API accessible Use Swagger!

×