Swagger – Cataloging With the World’s Most Popular Framework for APIs
I’ve posted a new blog on the Swagger suite of tools for API cataloging. You can find it here:
Here is a quick snippet from the introduction:
“As a developer in today’s tech industry, it’s almost guaranteed you will be developing and maintaining an API in your application. The simplistic nature of RESTful web services has driven the exponential growth of APIs. Despite this simplicity, developers often face a significant challenge once someone tries to consume the API. Take some time to think about how you develop your APIs. Are you documenting what your API actually does? And if so, is it up to date and does it cover all the details your consumer needs? Probably not. Why? Because writing a full API specification is REALLY boring and VERY tedious work, especially when APIs are added or change frequently. Next, what if your consumer wants to test your API? Do you send them a URL and say, “here, figure it out!” As a frequent consumer of APIs, that is often the response I get from consumers. Finally, is there nothing more annoying than a consumer that wants to know what type of error codes your API will respond with? Come on people! Just test the service and you can figure out the answers for yourself!
Now, what if a product existed that could help you auto-generate a significant amount of your API documentation? What if it followed a standard specification that could describe your API in the details that your consumer needs, including request parameters, response type and error codes? What if it displayed your API in a very readable format and even allowed a consumer to test the API? Well, that product does exist and its called Swagger.
Swagger is a powerful product that includes a standard specification, framework and tool set to support cataloging your APIs. In this blog post, I’ll demonstrate just how easy it is to get Swagger up and running in your application. I’ll cover the Swagger specification in details. I’ll walk through how you can annotate code to easily document an API and generate a Swagger specification. Then, I’ll show you how to use the Swagger UI tool to view and test out an API. By the end of this blog post, you’ll understand how cataloging an API with Swagger will increase the program-ability, governance and success of your APIs.”