Swagger is a tool that allows you to quickly and easily provide API documentation for your Web API project, and it’s free. Its official site is http://swagger.io/
Swagger is basically a framework for describing, consuming, and visualizing RESTful APIs. The nice thing about Swagger is that it really keeps the documentation system, the client, and the server code in sync always, in other words, the documentation of methods, parameters, and models is tightly integrated into the server code.
To implement "Swagger", you need to install "Swashbuckle". Swashbuckle is a combination of ApiExplorer and Swagger/swagger-ui and
provides a rich discovery, documentation, and playground experience to your API
consumers. Some of the features you get with Swashbuckle are:
- Auto-generated Swagger 2.0.
- Seamless integration of
swagger-ui.
- Reflection-based Schema
generation for describing API types.
- Extensibility hooks for
customizing the generated Swagger doc.
- Extensibility hooks for
customizing the swagger-ui.
- Out-of-the-box support for
leveraging Xml comments.
- Support for describing ApiKey,
Basic Auth and OAuth2 schemes. Including UI support for the Implicit
OAuth2 flow.
Add Swashbuckle using the NuGet package manager
console.
You can pass the version as well, but it’s optional; by default, it will pick the latest one.
After the package is installed, you will get a new file named SwagerConfig.cs under the App_Start folder.
To
check if swagger is integrated properly or not start a new debugging session (press
F5) and navigate to http://localhost:[PORT_NUM]/swagger. You should see Swagger UI help pages for your
APIs. Here you will see all your web API action methods.
Expand
an API, and clicking the "Try it out!" button will make a call to that
specific API and return results.
Enter the parameter in the textbox provided and click "Try it out!", you will get JSON data in the response body of this API. Also, you will get a Response Code and Response Headers. You can try all methods in this way, including all HttpMethod types.
Enable
Swagger to use XML comments.
In Solution Explorer, right-click on
the Web API project and click Properties. Click the Build tab
and navigate to Output. Make sure the XML documentation file is
checked. You can leave the default file path. In my case, it's bin\SwaggerDemoApi.XML
Now, add the
following line to SwaggerConfig.cs. Make sure to change the file path to the
path of your XML documentation file.
c.IncludeXmlComments($@"System.AppDomain.CurrentDomain.BaseDirectory}\bin\ProjectName.Api.XML");
The full
SwaggerConfig.cs is given below:
GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
c.SingleApiVersion("v1", "Project Name");
c.IncludeXmlComments($@"{System.AppDomain.CurrentDomain.BaseDirectory}\bin\ProjectName.XML");
})
.EnableSwaggerUi();
Swagger JSON
file
To
get the API’s complete metadata, navigate to the URL that is in the header of
the Swagger UI documentation page.
Copy the above URL and paste it into the browser, and you will get JSON data.
I hope this will help you. Do write a comment below.
🚀 "Happy Coding" 🚀
