There is a lot of discussion around the growth of APIs, and what the future will look like. How will we discover and make sense of the number of available APIs, and quickly get to work integrating with the APIs that bring the most value to our apps and businesses.
One technology that comes up in every conversation I’ve had is Swagger. What is Swagger?
Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services.
The goal of Swagger is to enable client and documentation systems to update at the same pace as the server. The documentation of methods, parameters and models are tightly integrated into the server code, allowing APIs to always stay in sync.
Swagger was born out of initiatives from Wordnik, developed for Wordnik’s own use during the development of developer.wordnik.com. Swagger development began in early 2010 and the framework being released is used by Wordnik’s APIs, which power both internal and external API clients.
Swagger provides a declarative resource specification, allowing users to understand and consume services without knowledge of server implementation, enabling both developers and non-developers to interact with the API, providing clear insight into how the API responds to parameters and options.
I’m familiarizing myself with the specification more and playing with the various tools they provide:
- Swagger Core - Defines Java annotations and required logic to generate a Swagger server or client.
- Swagger CodeGen - Contains a template-driven engine to generate client code in different languages by parsing your Swagger Resource Declaration.
- Swagger Scala Sample App - A fully-functioning, stand-alone Swagger server written in Scala which demonstrates how to enable Swagger in your API.
- Swagger Java Sample App - A fully-functioning, stand-alone Swagger server written in Java which demonstrates how to enable Swagger in your API.
I understand that Swagger is not the one specification to rule all APIs, and it won’t make all religious API fanatics happy. But I want to start somewhere. I see three main benefits for API owners coming from adopting Swagger:
- Automated, consistent generation of clean, beautiful, interactive API documentation
- Generation of client code and SDK in multiple languages
- Feeding into an industry wide API discovery language that both developers and non-developers can use
I believe strongly that consistent documentation and code samples ensure an API will get used, but as the number of APIs grows, a system like Google API Discovery Service, will be essential for API adoption across industries and around the globe. I’m hoping to learn more about Swagger, and see if it can help deliver on this vision.
|API Evangelist, Code LIbraries, Discovery, Documentation, Swagger, Wordnik|
blog comments powered by Disqus
Latest Blog Posts
- My First Keynote With The Infamous Audrey Watters
- Are You Going To Be At API Days in San Francisco? I Am!
- Updated API History White Paper
- History of APIs - Twilio
- API Providers Guide - API Design
- Box Opens Up Revenue Sharing For API Developers
- History of APIs - Mashery
- A Book API Platform
- History of APIs - del.icio.us
- API Management Using Github
- In The End API Providers Will Only Sell Bandwidth
- The Build-Up To #APIStrat in October
- APIdays Mediterranea Is A Wrap
- Helping EFF Urge The Courts to Block Copyright Claims in Oracle v. Google API Fight
- API Aggregation For Federal Government with FedAPI
- Have You Checked Out Webshell Lately?
- New Features From BaaS Provider AnyPresence
- Signals I Use To Monitor Companies In The API Space
- API Management Using APiphany
- Github Can Be More Than Code
- Quick Demonstration Showing The Benefits of The White House Digital Strategy
- IRS Needs To Use White House Open Data Policy For Guidance
- Dropbox As Your Apps Default File System
- DataSift's Open Source World
- Salesforce Adds Sandbox Templates