DownLoad Complete Project: WebApiDocumentationWithSwagger
“If it is not documented, it doesn’t exist. As long as information is retained in someone’s head, it is vulnerable to loss.”
That is absolutely valid when we talk about APIs, because any small-to-complex API needs to be documented, in order to make it easy to use. This might be an interesting challenge, because you have to find the bridge between the abstract world of computer programming and the way people think and work. Here is where Swagger shows its great utility.
Swagger is a specification for documenting REST API. It specifies the format (URL, method, and representation) to describe REST web services. Swagger is meant to enable the service producer to update the service documentation in real-time so that client and documentation systems are moving at the same pace as the server.
Microsoft also provide its own Api documentation libraries that automatically generates help page content for the web APIs on your site.The help page package is a good start but it is lacking things like discoverability and live interactions. This is where Swagger comes to the rescue.
Adding Swagger to your Web API does not replace ASP.NET Web API help pages. You can have both running side by side, if desired.
Adding swagger to Api Project
To add Swagger to an ASP.NET Web Api, we will install an open source project called Swashbuckle via nuget.
After the package is installed, navigate to App_Start in the Solution Explorer. You’ll notice a new file called SwaggerConfig.cs. This file is where Swagger is enabled and any configuration options should be set here.
Now you just need to set up Swagger by adding below code:
Start a new debugging session (F5) and navigate to
http://localhost:%5BPORT_NUM%5D/swagger. You should see Swagger UI help pages for your APIs.
Now you can see,all api methods of web api comes with pretty good documentation and you expand/hide the method definition.
Below is api controller code in which i created two methods that comes in swagger documentation.
if you expand method defination by click on individual methods,then you will find all required api level meta data like request,response.
The good thing about swagger is you can invoke api methods with swagger UI without using any external reset client like DHC,postman etc.There is “Try it now” button on each api method and you can call methods and get response from server.
Another useful feature of Swagger is to create a json document with the entire documentation of the API endpoints and models.
In order to open the json document, where your documentation is included, access the link on the top of the dashboard.
copy below highlighted url from swagger ui and enter in new browser tab.After that you will get pretty nice json document that contains all meta data about all api methods.
Below image shows json documentation.
you have an API which is documented and offers a nice experience to developers. You should keep in mind that this process of documenting APIs should start at the very beginning of the development process, for it to be easy to maintain.