RESTful services are becoming more prevalent in the systems we build and interact with. One of the problems with RESTful services is documentation. The documentation is either non-existent, out-dated and useless or done in Word completed separate from the actual code. Keeping the documentation up to date is also boring. Swagger.io gives you a way to overcome your RESTful service documentation problems by making your RESTful service’s documentation part of the code. Swagger.io gives you interactive documentation, i.e. no more boring Word documents, and the added bonuses of client SDK generation and discoverability.

2. • Every site, application, service and its dog offers a RESTFul API
• Your project probably has one too
• Microservices
• Client/Server
• BLL/UI
• Anything/Javascript
• Easy to understand
• Easy to learn
• Easy to adopt

3. • Resource
• Verbs
• Authentication
• Examples
• Sandbox
• Try it out

4. Adhoc
Source Code
Document
WADL

5. • Not XML, but a better abbreviation – JSON/YAML
• Includes information to help with discoverability
• Big adoption rate
• Plenty of tooling and community support

7. • Version 1.0 released in 2011
• Version 1.0 Tony Tam, version 2.0 400+ people
• Wordnik Reverb Software Smartbear
• Open source, Apache License, Version 2.0
• Gained a lot of momentum from 2013 to 2014
• Moved from Assess to Trail in the latest Thoughtworks
Technology Radar
• Microsoft Azure
• Amazon Web Services
• PayPal
• Apigee
• Etc… (go and check out their site)

8. • Browser based UI for exploring a Swagger defined API
• Java-related libraries for generating and reading
Swagger definitions
• Command-line tool for generating both client and server
side code from a Swagger definition
• Javascript client for swagger enabled API
• Java library to read swagger files
• Validates and adds a valid badge
• Browser based editor for authoring Swagger definitions
in YAML or JSON format

10. • All are some YAML like language with tools and generators
• RAML (RESTful API Modeling Language)
• API Blueprint
• APIDoc
• Some look nicer, some work easier, some are pricy
• Mashape
• API Designer Studio
• README Editor
• Apiary
• And on and on…

11. • What is your API used for and how?
• Who needs to setup the documentation
• Who needs to use the documentation
• Manual
• WADL or WADL like specifications
• No phoning a friend
• Project could end
• Slow bug fixes
• Can you still change what you are doing
now?
• Add the effort of setting things up