I'm developing REST services for some time for at my job and the most difficult part it's when I have to make a some changes to structure of the request/response objects and this is the result of the very nature of a REST service, a call made through an HTTP Request with a meaning full URL path like http://api.uber.com/products?localtion=lisbon where you normally receive a JSON result.
Usually a use a Swagger to generate a nice documentation so that clients can easily check the service details and test if needed, here an image with an example from a generate web API description from the swagger website:
The problem with JSON, despite of being so dynamic, we lose type and with this we lose tooling and compile time errors witch are handy to catch errors earlier than in runtime.
In the traditional way, where we use SOAP services (for instance WCF from Microsoft), you can use the WSDL file to generate the client proxy witch has all the methods available in the server and with the advantage of getting strongly typed classes witch it's awesome for tooling and intellisense.
But... there's hope, the team behind the Swagger tool created a nice "WSDL and Proxy Generator" for REST API's that generate code for all this languages
And this is so cool that this even allow us to generate the Server side code as well.
You can see in the demo editor page how this works, just select one of the dropdowns (Generate Server or Generate Client), select the language/framework and that's it, you will download a complete Server API or Proxy Client in the language of your choice. You can also edit the contents of your REST Service directly in the browser
Because I'm .NET developer, I use a :NET tool called Swashbuckle that it's a development by the .net community that uses All the Swagger features for .NET.
To see a complete list of Swagger Community integrations go here.
If you are a Web Developer and you're working on aweome and powerful RESTFull API that does wonders but you're struggling on way to create a documentation there are some great tools available out there.
It's easy to use so in this post I decided to add documentation using Swagger for a simple ASP.NET Web API project which contains a single controller with different HTTP methods
You can see a live demo API explorer here
, and the source code can be found on GitHub
. The final result for the API explorer will look as the image below:
Swagger is language-agnostic so there are different implementations for different platforms. For the ASP.NET Web API world there is a solid open source implementation named “Swashbuckle
Step 1 - Install Swashbuckle Nuget package
Install Nuget package by opening NuGet Package Manager Console and install the below package:
When the installation ends you can see a new class named swaggerconfig.cs inside your folder App_Start
Step 2 - Enable generating xml docs
Next right click in you your project (in my case WebApplication1) and select properties
When you are in the project properties select the build tab and then check the box that says XML documentation file and build your solution.
And that's it... to see your new REST API Documentation simply hit F5 and navigate to http://yourhost/swagger and voilá (in my case the url is http://localhost:56593/swagger)