Posted on 11-09-2011
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.
comments powered by Disqus
Winning in the API Economy
|Download as PDF|
Latest Blog Posts
- My Discussion Today With 6 Hypermedia Leaders At API-Craft in Detroit
- Getting To Know Jørn Wildt For The API Craft 2014 Detroit Hypermedia Panel
- Hypermedia Feels Like We Are Still Learning To Communicate With APIs
- Getting To Know Markus Lanthaler For The API Craft 2014 Detroit Hypermedia Panel
- Getting To Know Kevin Swiber For The API Craft 2014 Detroit Hypermedia Panel
- Getting To Know Steve Klabnik For The API Craft 2014 Detroit Hypermedia Panel
- New Indix API KickStart Program Reduces Costs For Developers
- Getting To Know Mike Kelly For The API Craft 2014 Detroit Hypermedia Panel
- A Shared, Distributed Experience(Metrics) Layer For The API Driven Application Stack
- Showcasing Your API Integrations With Other Platforms
- Increasing The Focus On APIs In Higher Education Is Important
- Getting To Know Mike Amundsen For The API Craft 2014 Detroit Hypermedia Panel
- The New StrongLoop API Server Provides A Look At Future Of API Deployment
- Models For API Driven Startups Built Around Public Data
- Will You Add Me To API Evangelist And How To Spot The Cool Kids
- When I Remix APIs Using Swagger How Do I Deal With Authentication Across Multiple APIs
- It Takes A Team Of Evangelists To Raise An API
- Support For Only Two Creative Commons Licenses In The API Commons
- Machine Readable Terms of Service Didn't Read Applied To APIs Via APIs.json
- API Deployment For Non-Developers Using Zapier, Google Docs, and APISpark
- State of Hypermedia Today @ API Craft In Detroit
- Need A Formal API Standard For Your Government Agency? Fork 18F's, And Make It Your Own!
- CORS Makes Your API Portable And Remix-able
- Chief Data Officer Needs To Make The Department Of Commerce Developer Portal The Center Of API Economy
- An API Definition As The Truth In The API Contract