Web API Documentation using Swagger
Swagger is the best way to create proper documentation for your web API. Creating documentation for your Web API is a huge success.Swagger is framework for describing you API.
Steps to Add Swashbuckle to ASP.NET Web API
1. Install the Nuget Package
Open NuGet Package Manager Console and install the below package:
Install-Package Swashbuckle
Or
Right click on the API Project and click Manage NuGet Package and search "SwashBuckle" as shown in below screenshot.
Right click on the API Project and click Manage NuGet Package and search "SwashBuckle" as shown in below screenshot.
Once this package is installed it will install a bootstrapper (App_Start/SwaggerConfig.cs) file which initiates Swashbuckle on application.
Run you Web API Project and write "Swagger" at the end of the URL.
Same in case of POST method. you can test you POST method directly form this page.
2. Enable generating XML documentation
This is not a mandatory step however, it is quite useful when you are using complex model.
Right click on your API Project ---> Go to Properties --> Select Build
See the below screenshot.
Select the checkbox "XML" documentation file.
Go to App_Start and open Swagger.config. Use the code below and give the same path that you mentioned in Step 2. This setting is only for version 4.1.0. For above version like 5.0 no need to do below settings. As Bootstrapper is not available in new version.
See the below screenshot.
Select the checkbox "XML" documentation file.
3. Configure Swashbuckle for using XML Comments
public class SwaggerConfig
{
public static void Register()
{
Swashbuckle.Bootstrapper.Init(GlobalConfiguration.Configuration);
SwaggerSpecConfig.Customize(c =>
{
c.IncludeXmlComments(GetXmlCommentsPath());
});
}
private static string GetXmlCommentsPath()
{
return Path.Combine(System.Web.HttpRuntime.AppDomainAppPath, "bin", "DentalServices.CarrierBestWay.Api.XML");
}
}
4. Annotating your API methods
Open your Controller Web API method and add Response Type. Again this is not mandatory to add Response Type but it is quite helpful to get your method information.
[HttpPost]
[ResponseType(typeof(Rule))]
public IHttpActionResult Post(Rule model)
{
//your code
}
5. Run the Swagger
like this http://localhost:64850/swagger.
The page will open like below screenshot which contains all you web API methods
with Response Type description. You can run you method directly from here like Chrome PostMan and Fiddler. It is very helpful.
The page will open like below screenshot which contains all you web API methods
with Response Type description. You can run you method directly from here like Chrome PostMan and Fiddler. It is very helpful.
In attached screenshot there are 2 methods, one for GET and one for POST. Click on GET method it will expand like below screenshot form where you can run you GET method directly from here. See Press the "try it out" button. It is giving the description that in GET method you will get Rule collection.
Same in case of POST method. you can test you POST method directly form this page.
