Swagger - Design and Document your REST APIs
Post on 15-Apr-2017
276 Views
Preview:
Transcript
Design, build & document your REST APIs
Tai Shi Ling
Full Stack Web App Developer
Co-founder, Uilicious
I need to document my REST APIs.
I used to document them on wiki like this:
But I find myself spending more time on formatting then writing the docs.
How can I generate my documentation?
Nice.You can generate documentation!
But… how do I tell people the schema for the request?
Open API Specification aka SWAGGER Specification
Framework for describing APIs for the discovery of APIs by humans and machines
Open API Specification aka SWAGGER Specification
Like WSDL is for SOAP APIs.
How can I generate my documentation?
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?
Swagger specs look like this:
YAML or JSON
It’s easy to learn!
Design Swagger Editor Build Swagger CodeGen Document Swagger UI
Core Tools
Design | Swagger EditorCode completion Error checking Preview & test APIs
Build | Swagger CodeGenGenerate server stub code (>20 languages) Generate client SDKs (>40 languages)
Document | Swagger UIAPI explorer
Plug in a url to any swagger doc to explore its APIs
Document | Swagger UI
Let’s add some SWAGGER to our APIs
Design | Swagger Editor
Installation is super easy
2. Docker:
docker pull swaggerapi/swagger-editordocker run -p 80:8080 swaggerapi/swagger-editor
Design | Swagger Editor
3. NodeJS:
git clone https://github.com/swagger-api/swagger-editor.gitcd swagger-editornpm installnpm start
Design | Swagger Editor
How to write a SWAGGER Spec
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.
Document | Swagger UI
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
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:
I hope my docs look like this in the future:
What about alternatives?
RESTful API Modeling Language- YAML syntax - Hierarchical schema
What about alternatives?
- Markdown Syntax - Hierarchical schema
Why Swagger?
Large Community
Why Swagger?Comprehensive Schema
Why Swagger?Large Ecosystem
Why Swagger?Large Ecosystem
Why Swagger?
Flat schema is more readable. :)
Some nice resources
Tutorial: http://idratherbewriting.com/pubapis_swagger/
top related