Get Started with Swashbuckle and ASP.NET Core

This article is intended to add some supplementary information to the official documentation in Microsoft Docs. My goal is to connect the dots between the code/comments and the Swagger UI elements.

We will first go over the configurations for Swachbuckle, then investigate the Swagger UI and code comments in XML and Markdown. It should be helpful for quickly setting up a Web API project with Swagger.

Swagger/OpenAPI

We often see that people use Swagger and OpenAPI interchangeably. A blog in swagger.io describes some subtle differences between Swagger and OpenAPI.

OpenAPI refers to the OpenAPI Specification (OAS) developed and supported by the Open API Initiative (OAI). The OAS describes the capabilities of API endpoints, and the OAS is language-agnostic and framework-agnostic. The OAS v3.0, released in 2017, is sometimes shortened to OAS3. By default, the specification is presented in a document named swagger.json.

Swagger refers to the tools for implementing the OAS, which for example, is described in the swagger.json file. The Swagger tooling ecosystem, including Swagger Editor, Swagger UI, Swagger Codegen, etc., helps developers generate useful documentation and interactive pages for Web APIs. Different programming languages and frameworks have their own implementations of OAS.

In this article, we will focus on the library SwashBuckle.AspNetCore, which is an implementation of Swagger/OpenAPI. We will take a look at an ASP.NET Core Web API project, and identify the relationships between the SwashBuckle configurations and the Swagger UI representation.

Add Swashbuckle to an ASP.NET Core Project

It is easy to add Swashbuckle to our web projects. We first install the latest version of the NuGet package Swashbuckle.AspNetCore, then add the following code snippet to the Startup class. That’s all we have to do.