Swagger: Restful documentation that won't put you to sleep
0 likes145 views
The document discusses the prevalence and advantages of RESTful APIs in modern projects, highlighting their ease of use and community support. It mentions various tools, libraries, and languages designed to facilitate API design, such as Swagger, RAML, and API Blueprint. Additionally, it addresses the importance of documentation and the challenges involved in maintaining it.
Swagger: Restful documentation that won't put you to sleep
- 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
- 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