Creating APIs to be consumed by 3rd party applications (public API) have become very important especially with the explosive growth witnessed by mobile apps. Exposing RESTful end points for consumption by mobile apps (or any application) involves lot of testing to generate stable APIs.
When the endpoints are to be consumed by other public applications then a strong and simplified documentation with sample usage becomes all the more important. Following up with the consumers regarding the usage is the last thing one would want to do after the development of RESTful services.
As you services evolve during the development phase, keeping up with the documentation poses a real challenge. It becomes increasingly difficult to be sure whether the document is a true reflection of the APIs, meaning whether the document is 'live'.
To make the document generation process less painful and ensuring that it is always 'live', several tools have been developed. One such tool, which I found useful is 'Swagger'. This tool allows your API to be documented in real-time and that too without writing a single line of code. Now, how cool is that !
Pre-requisites: I am assuming that you already have an ASP.NET WebApi project created and that you are able to access some of the RESTful endpoints. For Swagger to work, your controller must be derived from ApiController base class.
My WebApi would be a self hosted one so the following steps are valid for self hosted services.
1) Please install the swashbuckle nuget package in your web api project either using the Package Manager console or 'Manage Nuget Packages' control menu.
PM> install-package swashbuckle
Then, install swashbuckle.core package in similar way.
PM> install-package swashbuckle.core
After installing the above packages, a new .cs file names "SwaggerConfig" would be created in the App_Start folder. This file contains the code to activate your WebApi.
That's it. Now run your WebApi project and browse the following URL,
"http://localhost:<your port no.>/swagger/"
The highlighted text is the name of the controllers in my Web Api. If you Expand Operations then you also have the facility to invoke the API and check the result.
Now, you will never have to maintain the documents for your public APIs. It is all embedded in your code.
When the endpoints are to be consumed by other public applications then a strong and simplified documentation with sample usage becomes all the more important. Following up with the consumers regarding the usage is the last thing one would want to do after the development of RESTful services.
As you services evolve during the development phase, keeping up with the documentation poses a real challenge. It becomes increasingly difficult to be sure whether the document is a true reflection of the APIs, meaning whether the document is 'live'.
To make the document generation process less painful and ensuring that it is always 'live', several tools have been developed. One such tool, which I found useful is 'Swagger'. This tool allows your API to be documented in real-time and that too without writing a single line of code. Now, how cool is that !
Pre-requisites: I am assuming that you already have an ASP.NET WebApi project created and that you are able to access some of the RESTful endpoints. For Swagger to work, your controller must be derived from ApiController base class.
My WebApi would be a self hosted one so the following steps are valid for self hosted services.
1) Please install the swashbuckle nuget package in your web api project either using the Package Manager console or 'Manage Nuget Packages' control menu.
PM> install-package swashbuckle
Then, install swashbuckle.core package in similar way.
PM> install-package swashbuckle.core
After installing the above packages, a new .cs file names "SwaggerConfig" would be created in the App_Start folder. This file contains the code to activate your WebApi.
That's it. Now run your WebApi project and browse the following URL,
"http://localhost:<your port no.>/swagger/"
The highlighted text is the name of the controllers in my Web Api. If you Expand Operations then you also have the facility to invoke the API and check the result.
Now, you will never have to maintain the documents for your public APIs. It is all embedded in your code.
