Handcrafting Swagger

What is Swagger

Swagger is a new way of defining API or web service endpoints currently being maintained by SmartBear the makers of SoapUI.  The concept is to provide an easy way of describing what an API does which is readable both by humans and by machines.  I want to in this post walk through a handcrafted approach to defining an API using the swagger syntax.

Creating a Swagger File
I have created a minimal swagger.json file below showing settings that will form a basic file.  In this case I have created a title and a plain english description and have defined the host for the API which will run of my personal hosting for now.

{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Blog Updater API",
"description": "This API is called to update one or more blogs with specified content.",
"termsOfService": "http://homesite.munceyweb.com/api/blogupdater/terms/",
"contact": {
"name": "API Support",
"url": "http://homesite.munceyweb.com/api/blogupdater/support",
"email": "api.support@munceyweb.com"
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
}
},
"host": "http://munceyweb.com"
}

Generating API Documents
I downloaded the swagger UI from https://github.com/swagger-api/swagger-ui and copied the contents of the dist folder into a local folder on my PC. I then put the swagger.json file above into the folder.  If you have python install on your PC you can take advantage of the simple HTTP server which python provides. To do this I opened a command prompt, changed directory to the local folder with the swagger ui and typed “python -m http.server”. This started a basic HTTP server on my PC. I then opened http://localhost:8000 in my browser and after entering http://localhost:8000 got the first look at my API as documentation.

Comments

Leave a Reply

Your email address will not be published.