Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Swagger - Design and Document your REST APIs

917 views

Published on

Introduction to Open API specification, a.k.a. Swagger specification.

These are slides for my talk:
https://www.youtube.com/watch?v=y-34F7FbfiM&t=1063s
The talk includes a live demonstration on writing a Swagger specification and short Q&A segment.

Enjoy!

This talk was hosted by the API Craft Singapore Meetup group (https://www.meetup.com/API-Craft-Singapore/) in December 2016.

Published in: Software

Swagger - Design and Document your REST APIs

  1. 1. Design, build & document your REST APIs
  2. 2. Tai Shi Ling Full Stack Web App Developer Co-founder, Uilicious
  3. 3. I need to document my REST APIs.
  4. 4. I used to document them on wiki like this:
  5. 5. But I find myself spending more time on formatting then writing the docs.
  6. 6. How can I generate my documentation?
  7. 7. Nice.You can generate documentation!
  8. 8. But… how do I tell people the schema for the request?
  9. 9. Open API Specification aka SWAGGER Specification Framework for describing APIs for the discovery of APIs by humans and machines
  10. 10. Open API Specification aka SWAGGER Specification Like WSDL is for SOAP APIs.
  11. 11. How can I generate my documentation?
  12. 12. How can I prototype my APIs? How can I validate my APIs? How can I keep my specs and documentation in sync? How can I share my API specs?
  13. 13. Swagger specs look like this: YAML or JSON It’s easy to learn!
  14. 14. Design Swagger Editor Build Swagger CodeGen Document Swagger UI Core Tools
  15. 15. Design | Swagger Editor Code completion Error checking Preview & test APIs
  16. 16. Build | Swagger CodeGen Generate server stub code (>20 languages) Generate client SDKs (>40 languages)
  17. 17. Document | Swagger UI API explorer Plug in a url to any swagger doc to explore its APIs
  18. 18. Document | Swagger UI
  19. 19. Let’s add some SWAGGER to our APIs
  20. 20. Design | Swagger Editor
  21. 21. Installation is super easy
  22. 22. Design | Swagger Editor 1. No Installation: editor.swagger.io
  23. 23. 2. Docker: docker pull swaggerapi/swagger-editor docker run -p 80:8080 swaggerapi/swagger-editor Design | Swagger Editor
  24. 24. 3. NodeJS: git clone https://github.com/swagger-api/swagger-editor.git cd swagger-editor npm install npm start Design | Swagger Editor
  25. 25. How to write a SWAGGER Spec
  26. 26. Wait, there’s more! http://swagger.io/specification/
  27. 27. Design | Swagger Editor Things to note… Getting around CORs: https://github.com/swagger-api/swagger-editor/blob/master/docs/cors.md Study at your leisure.
  28. 28. Document | Swagger UI
  29. 29. Document | Swagger UI 1. Clone or download Swagger UI: https://github.com/swagger-api/swagger-ui 2. Open ./dist/index.html in your fav text editor 3. Change the default url to your swagger file location 4. Open ./dist/index.html in your browser
  30. 30. Document | ReDoc https://github.com/Rebilly/ReDoc
  31. 31. Document | ReDoc <!DOCTYPE html> <html> <head> <title>ReDoc</title> <!-- needed for adaptive design --> <meta name="viewport" content="width=device-width, initial-scale=1"> <!-- ReDoc doesn't change outer page styles --> <style> body { margin: 0; padding: 0; } </style> </head> <body> <redoc spec-url='http://petstore.swagger.io/v2/swagger.json'></redoc> <script src="https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js"> </script> </body> </html> All you need is:
  32. 32. I hope my docs look like this in the future:
  33. 33. What about alternatives? RESTful API Modeling Language - YAML syntax - Hierarchical schema
  34. 34. What about alternatives? - Markdown Syntax - Hierarchical schema
  35. 35. Why Swagger? Large Community
  36. 36. Why Swagger? Comprehensive Schema
  37. 37. Why Swagger? Large Ecosystem
  38. 38. Why Swagger? Large Ecosystem
  39. 39. Why Swagger? Flat schema is more readable. :)
  40. 40. Some nice resources Tutorial: http://idratherbewriting.com/pubapis_swagger/

×