Swagger: Restful documentation that won't put you to sleep

• 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

• Resource• Verbs

• Authentication• Examples

• Sandbox• Try it out

Adhoc

Source Code

Document

WADL

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

• 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)

• 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

• 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…

• 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