What is Swagger

Swagger is a very much used open source framework backed by a large ecosystem of tools that helps you design, build, document, and consume your RESTful APIs. It is probably becoming as the main standard for this domain (APIs description metadata).

The heart of Swagger is the Swagger Specification (API description metadata which is a JSON or YAML file). The specification creates the RESTful contract for your API, detailing all of its resources and operations in a human and machine readable format for easy development, discovery, and integration.

The specification is the basis of the OpenAPI Specification (OAS) and is developed in an open, transparent, and collaborative community to standardize the way RESTful interfaces are defined.

This specification defines the structure for how a service can be discovered and its capabilities understood. More information, a Web Editor, and examples of Swaggers from companies like Spotify, Uber, Slack, Microsoft and many more can be found at http://swagger.io

Why to use Swagger

The main reasons why you would want to generate Swagger metadata about your APIs are basically the following:

– Ability to automatically consume and integrate your APIs with tens of products and commercial tools supporting Swagger plus many libraries and frameworks serving the Swagger ecosystem. Microsoft has high level products and tools that can automatically consume Swagger based APIs, like the following:

o Microsoft Flow – Ability to automatically use and integrate your API into a high-level Microsoft Flow workflow, with no programming skills required.

o Microsoft PowerApps – Ability to automatically consume your API from PowerApps mobile apps built with PowerApps Studio, with no programming skills required.

o Azure App Service Logic Apps – Ability to automatically use and integrate your API into an Azure App Service Logic App, with no programming skills required.

– APIs documentation automatically generated – When creating large scale RESTful APIs, like when building complex microservice based applications, you will need to handle a large number of endpoints with different data models used in the request/response payloads. Proper documentation and having a solid API explorer is a crucial pillar for your API success and likability by developers.

Swagger’s metadata is basically what Microsoft Flow, PowerApps and Azure Logic Apps use to understand how to use services/APIs and connect to it.

How to automate API Swagger metadata generation with Swashbuckle NuGet package from your ASP.NET Core Web APIs

Generating Swagger metadata manually (JSON or YAML file) can be a tedious work if you have to write it manually. However, you can automate API discovery of ASP.NET Web API services by using the Swashbuckle NuGet package to dynamically generate Swagger API metadata.

Swashbuckle is seamlessly and automatically adds Swagger metadata to ASP.NET Web Api projects. Depending on the package version, it supports ASP.NET Core Web API projects and the traditional ASP.NET Web API and any other “flavor” like Azure API App, Azure Mobile App, Azure Service Fabric microservices based on ASP.NET or plain Web API on containers, as in this case.

Swashbuckle combines ApiExplorer and Swagger/swagger-ui to provide a rich discovery and documentation to your API consumers.

In addition to its Swagger metadata generator engine, Swashbuckle also contains an embedded version of swagger-ui which it will automatically serve up once Swashbuckle is installed.

This means you can complement your API with a slick discovery UI to assist developers with their integration efforts. Best of all, it requires minimal coding and maintenance because it is automatically generated, allowing you to focus on building your API. The final result for the API explorer will look as the image below.

But that UI explorer is not the most important thing here, as mentioned, once you have a Web API that can describe itself in Swagger metadata, your API can seamlessly be used from Swagger-based tools including client proxy classes code generator that can target many platforms, like using swagger-codegen, for example, which allows code generation of API client libraries, server stubs and documentation automatically.

Currently, Swashbuckle consists of two NuGet packages – Swashbuckle.SwaggerGen and Swashbuckle.SwaggerUi. The former provides functionality to generate one or more Swagger documents directly from your API implementation and expose them as JSON endpoints. The latter provides an embedded version of the swagger-ui tool that can be served by your application and powered by the generated Swagger documents to describe your API.

Once you have installed those Nuget packages on your Web API project, you will need to configure Swagger in your Startup.cs class, as in the following code in your ASP.NET Core Web API project:

Once this is done, you should be able to spin up your app and browse the following Swagger JSON and UI endpoints respectively.

You previously showed the generated UI created by Swashbuckle with the URL “<your-root-url>/swagger/ui”. Below you can also see how you can test any specific API method.

Now, the following image is the Swagger JSON metadata generated from the eShopOnContainer microservice (which is really what the tools use underneath) when you test it and request that <your-root-url>/swagger/v1/swagger.json URL using the convenient Postman tool.

It is that simple, and because it is automatically generated, the Swagger metadata will grow while you add more functionality to your API.

NOTE: Currently, Swashbuckle 6.0.0 version is what you need to use for ASP.NET Core Web API projects which is by the way the most common case when building Docker containers with .NET Core (as in the code I’m testing using Docker), but you can also use plain ASP.NET Core on Linux or Windows, with no Docker, of course.

If using the traditional .NET Framework for Windows, you need to use a different NuGet package version.