Adding Swagger to your Web API project does not replace ASP.NET Web API help pages (here the NuGet package for Microsoft ASP.NET Web Api Help Page). You can have both running side by side, if desired.
To add Swagger to an ASP.NET Web Api, we will install an open source project called Swashbuckle via nuget.
Install-Package Swashbuckle –Version 5.2.1
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.
Configuring Swagger
At minimum you’ll need this line to enable Swagger and Swagger UI.
GlobalConfiguration.Configuration .EnableSwagger(c => c.SingleApiVersion("v1", "A title for your API")) .EnableSwaggerUi();
Start a new debugging session (F5) and navigate to https://localhost:[PORT_NUM]/swagger. You should see Swagger UI help pages for your APIs.
Expanding an api and clicking the “Try it out!” button will make a call to that specific API and return results.
And then you see the response:
Enable Swagger to use XML comments
The minimum configuration is nice to get started but let’s add some more customization. We can tell Swashbuckle to use XML comments to add more details to the Swagger metadata. These are the same XML comments that ASP.NET Help Pages uses.
First, enable XML documentation file creation during build. In Solution Explorer right-click on the Web API project and click Properties. Click the Build tab and navigate to Output. Make sure XML documentation file is checked. You can leave the default file path. In my case its bin\SwaggerDemoApi.XML
Next, we need to tell Swashbuckle to include our XML comments in the Swagger metadata. Add the following line to SwaggerConfig.cs. Make sure to change the file path to the path of your XML documentation file.
GlobalConfiguration.Configuration .EnableSwagger(c => { c.SingleApiVersion("v1", "SwaggerDemoApi"); c.IncludeXmlComments(string.Format(@"{0}\bin\SwaggerDemoApi.XML", System.AppDomain.CurrentDomain.BaseDirectory)); }) .EnableSwaggerUi();
Finally, if you haven’t already, add XML comments to your Models and API methods.
Run the project and navigate back to /swagger. You should see more details added to your API documentation. I’ve highlighted a few below with their corresponding XML comment.
Under Response Class, click Model. You should see any XML comments added to your models.
Describing Enums As Strings
My Superhero class contains an Enum property called Universe which represents which comic universe they belong to.
By default, Swagger displays these Enum values as their integer value. This is not very descriptive. Let’s change it to display the string representation.
GlobalConfiguration.Configuration .EnableSwagger(c => { c.SingleApiVersion("v1", "SwaggerDemoApi"); c.IncludeXmlComments(string.Format(@"{0}\bin\SwaggerDemoApi.XML", System.AppDomain.CurrentDomain.BaseDirectory)); c.DescribeAllEnumsAsStrings(); }) .EnableSwaggerUi();
If I look at Swagger now, the Universe Enum values are displayed as strings.
These are just a few of the many configuration options you can specify in Swashbuckle to create your Swagger metadata. I encourage you to review the other options on Swashbuckle’s GitHub.
Conclusion
Finally, you know how adding Swagger to your Web API project. Happy coding!
[…] Swagger UI to your Azure Function APIs allows you for providing documentation for your serverless API pretty […]
[…] parameter -S means you want to add Swagger to your […]
[…] Adding Swagger To Web API Project […]