Downloaded 63 times
Swagger - Design and Document your REST APIs
- 1. Design, build &document your REST APIs
- 2. Tai Shi Ling FullStack Web App Developer Co-founder, Uilicious
- 3. I need todocument my REST APIs.
- 4. I used todocument them on wiki like this:
- 7. But I findmyself spending more time on formatting then writing the docs.
- 8. How can Igenerate my documentation?
- 10. Nice.You can generatedocumentation!
- 11. But… how doI tell people the schema for the request?
- 14. Open API Specification akaSWAGGER Specification Framework for describing APIs for the discovery of APIs by humans and machines
- 15. Open API Specification akaSWAGGER Specification Like WSDL is for SOAP APIs.
- 16. How can Igenerate my documentation?
- 17. How can Iprototype 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?
- 18. Swagger specs looklike this: YAML or JSON It’s easy to learn!
- 19. Design Swagger Editor BuildSwagger CodeGen Document Swagger UI Core Tools
- 20. Design | SwaggerEditor Code completion Error checking Preview & test APIs
- 21. Build | SwaggerCodeGen Generate server stub code (>20 languages) Generate client SDKs (>40 languages)
- 22. Document | SwaggerUI API explorer Plug in a url to any swagger doc to explore its APIs
- 23.
- 24. Let’s add someSWAGGER to our APIs
- 25. Design | SwaggerEditor
- 26.
- 27. Design | SwaggerEditor 1. No Installation: editor.swagger.io
- 28. 2. Docker: docker pullswaggerapi/swagger-editor docker run -p 80:8080 swaggerapi/swagger-editor Design | Swagger Editor
- 29. 3. NodeJS: git clonehttps://github.com/swagger-api/swagger-editor.git cd swagger-editor npm install npm start Design | Swagger Editor
- 30. How to writea SWAGGER Spec
- 31.
- 32. Design | SwaggerEditor Things to note… Getting around CORs: https://github.com/swagger-api/swagger-editor/blob/master/docs/cors.md Study at your leisure.
- 33.
- 34. Document | SwaggerUI 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
- 35.
- 36. Document | ReDoc <!DOCTYPEhtml> <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:
- 37. I hope mydocs look like this in the future:
- 38. What about alternatives? RESTfulAPI Modeling Language - YAML syntax - Hierarchical schema
- 39. What about alternatives? -Markdown Syntax - Hierarchical schema
- 40.
- 41.
- 42.
- 43.
- 44. Why Swagger? Flat schemais more readable. :)
- 45.