swagger - design and document your rest apis
TRANSCRIPT
![Page 1: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/1.jpg)
Design, build & document your REST APIs
![Page 2: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/2.jpg)
Tai Shi Ling
Full Stack Web App Developer
Co-founder, Uilicious
![Page 3: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/3.jpg)
I need to document my REST APIs.
![Page 4: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/4.jpg)
I used to document them on wiki like this:
![Page 5: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/5.jpg)
![Page 6: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/6.jpg)
![Page 7: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/7.jpg)
But I find myself spending more time on formatting then writing the docs.
![Page 8: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/8.jpg)
How can I generate my documentation?
![Page 9: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/9.jpg)
![Page 10: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/10.jpg)
Nice.You can generate documentation!
![Page 11: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/11.jpg)
But… how do I tell people the schema for the request?
![Page 12: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/12.jpg)
![Page 13: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/13.jpg)
![Page 14: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/14.jpg)
Open API Specification aka SWAGGER Specification
Framework for describing APIs for the discovery of APIs by humans and machines
![Page 15: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/15.jpg)
Open API Specification aka SWAGGER Specification
Like WSDL is for SOAP APIs.
![Page 16: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/16.jpg)
How can I generate my documentation?
![Page 17: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/17.jpg)
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?
![Page 18: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/18.jpg)
Swagger specs look like this:
YAML or JSON
It’s easy to learn!
![Page 19: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/19.jpg)
Design Swagger Editor Build Swagger CodeGen Document Swagger UI
Core Tools
![Page 20: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/20.jpg)
Design | Swagger EditorCode completion Error checking Preview & test APIs
![Page 21: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/21.jpg)
Build | Swagger CodeGenGenerate server stub code (>20 languages) Generate client SDKs (>40 languages)
![Page 22: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/22.jpg)
Document | Swagger UIAPI explorer
Plug in a url to any swagger doc to explore its APIs
![Page 23: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/23.jpg)
Document | Swagger UI
![Page 24: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/24.jpg)
Let’s add some SWAGGER to our APIs
![Page 25: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/25.jpg)
Design | Swagger Editor
![Page 26: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/26.jpg)
Installation is super easy
![Page 28: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/28.jpg)
2. Docker:
docker pull swaggerapi/swagger-editordocker run -p 80:8080 swaggerapi/swagger-editor
Design | Swagger Editor
![Page 29: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/29.jpg)
3. NodeJS:
git clone https://github.com/swagger-api/swagger-editor.gitcd swagger-editornpm installnpm start
Design | Swagger Editor
![Page 30: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/30.jpg)
How to write a SWAGGER Spec
![Page 32: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/32.jpg)
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.
![Page 33: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/33.jpg)
Document | Swagger UI
![Page 34: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/34.jpg)
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
![Page 36: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/36.jpg)
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:
![Page 37: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/37.jpg)
I hope my docs look like this in the future:
![Page 38: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/38.jpg)
What about alternatives?
RESTful API Modeling Language- YAML syntax - Hierarchical schema
![Page 39: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/39.jpg)
What about alternatives?
- Markdown Syntax - Hierarchical schema
![Page 40: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/40.jpg)
Why Swagger?
Large Community
![Page 41: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/41.jpg)
Why Swagger?Comprehensive Schema
![Page 42: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/42.jpg)
Why Swagger?Large Ecosystem
![Page 43: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/43.jpg)
Why Swagger?Large Ecosystem
![Page 44: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/44.jpg)
Why Swagger?
Flat schema is more readable. :)
![Page 45: Swagger - Design and Document your REST APIs](https://reader033.vdocument.in/reader033/viewer/2022051404/587a46c51a28ab00148b5675/html5/thumbnails/45.jpg)
Some nice resources
Tutorial: http://idratherbewriting.com/pubapis_swagger/