Swagger - make your API accessible
Download as PPTX, PDF23 likes16,443 views
This document introduces Swagger, an open-source framework for describing, producing, consuming, and visualizing RESTful APIs. It provides a specification for describing APIs in a machine-readable format. Swagger allows automatically generating documentation from code and enabling tooling around REST APIs. The document discusses Swagger specifications, how to list and view API details, integration with various programming languages and frameworks, development and deployment processes, and alternatives to Swagger.
Swagger - make your API accessible
- 1. Swagger Make your API accessible Victor Trakhtenberg victortr75@gmail.com @victortr75
- 2. Personal My name is Victor Almost 15 years of software development Chief Architect @
- 4. Architecture APIs are for humans Documentation http://www.infoq.com/resource/presentations/API-Humans/en/slides/sl23.jpg
- 6. Documentation • No standard • Ad-hoc attributes • Managed manually • Not up to date • ….. http://www.imagineyourreality.com/business-coaching/documentation.html
- 7. API Listing
- 9. API parameters and return types
- 10. Swagger is… • producing • consuming • visualizing RESTful APIs A framework for • describing • documenting RESTful APIs A specification for Technology Methodology
- 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. Agenda • Introduction • Deep Dive • The technology • Swagger is not • Alternatives • Dev process • Deployment process • References
- 13. Deep Dive
- 14. Swagger - API Listing
- 15. Swagger - API Listing - JSON
- 16. Swagger – API Listing - Annotations
- 17. Swagger - API Details
- 18. Swagger – Test the API
- 19. Swagger - API Details - JSON
- 20. Swagger – API Details - Annotations
- 21. The Technology
- 22. Reverb - Wordnik Atmosphere – Scalatra – JSON4S
- 23. The Technology – Scala based • swagger-core • swagger-codegen • swagger-ui
- 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. Client code generation • Java • Scala • Groovy • Clojure • Python • Ruby • ObjectiveC • C# • PHP • Javascript • Custom • Uses {{mustache}} templates
- 26. Swagger is not
- 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. Alternatives
- 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. Dev Process
- 31. API development approaches API specification first –Write the JSON spec –Generate the API stubs –Implement the APIs –Publish
- 32. API development approaches API implementation first –Implement the API –Put the annotations in place
- 34. Dev/Test environment Annotate the APIs Make swagger UI accessible from the application itself
- 35. Dev/Test environment View the documentation locally Test the APIs using swagger UI
- 36. Dev/Test environment Generate internal clients based on swagger specification
- 37. Production environment Make swagger UI NOT accessible from the application itself
- 38. Production environment Automatically generate external swagger static resources
- 39. Production environment Deploy on dedicated web server Synchronize the documentation
- 40. Production environment Generate external clients based on swagger specification
- 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. Make your API accessible Use Swagger!