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.
|Code LIbraries, Discovery, Documentation, Swagger, Wordnik|
blog comments powered by Disqus
Latest Blog Posts
- APIs in DFW
- Adding API Broker Under Monitoring for API Aggregators
- The Dark Matter That Make APIs Work
- Potential for API Aggregators to Provide Valuable Industry Data
- My Talk Tomorrow Night at the Dallas-Forth Worth API Professionals Meetup
- The White House Releases An Open Data Strategy
- When API Success Signals Begin Working Against You
- Get To Know Which Languages Your API Developers Are Using
- Twitters Developer Area is More Embeddable Than API
- Overview Of Backend as a Service (BaaS) White Paper
- Make Sure And Have Multiple KPIs For Your APIs
- API Enabled Toys For Our Children
- I Am Speaking At The Dallas-Forth Worth API Professionals Meetup May 14th
- How Much Do You Spend Attracting and Supporting Freemium API Developers?
- What Does The API Evangelist Do?
- Startups Need To Work Together on API Definitions
- Parse Is Successful By Truly Solving Problems for Mobile Developers
- API Commandment: Thou Shalt Not Forego Talking to a Person
- API Trends
- API Priorities
- Have You Taken A Look At AT&T APis Lately?
- Helping People Understand APIs Through Real World Examples
- Evolving Beyond API Service Providers and Tools to Goal Based API Toolkits
- APIs & The Federal Government
- After Last Couple of Weeks, It's Clear There Is Big Opportunity In The API Space