Why use Swagger? The main reasons to generate Swagger metadata for your APIs are the following.
Ability for other products to automatically consume and integrate your APIs . Dozens of products
and
commercial tools
and many
libraries and frameworks
support Swagger. Microsoft has high-level
products and tools that can automatically consume Swagger-based APIs, such as the following:
•
AutoRest
. You can automatically generate .NET client classes for calling Swagger. This tool can
be used from the CLI and it also integrates with Visual Studio for easy use through the GUI.
•
Microsoft Flow
. You can automatically
use and integrate your API
into a high-level Microsoft
Flow workflow, with no programming skills required.
•
Microsoft PowerApps
. You can automatically consume your API from
PowerApps mobile apps
built with
PowerApps Studio
, with no programming skills required.
•
Azure App Service Logic Apps
. You can automatically
use and integrate your API into an Azure
App Service Logic App
, with no programming skills required.
Ability to automatically generate API documentation . When you create large-scale RESTful APIs,
such as complex microservice-based applications, you need to handle many endpoints with different
data models used in the request and response payloads. Having proper documentation and having a
solid API explorer, as you get with Swagger, is key for the success of your API and adoption by
developers.
Swagger’s metadata is what Microsoft Flow, PowerApps, and Azure
Logic Apps use to understand how
to use APIs and connect to them.
There are several options to automate Swagger metadata generation for ASP.NET Core REST API
applications, in the form of functional API help pages, based on
swagger-ui .
Probably the best know is
Swashbuckle
, which is currently used in
eShopOnContainers
and we’ll cover
in some detail in this guide but there’s also the option to use
NSwag
, which can generate Typescript
and C# API clients, as well as C# controllers, from a Swagger or OpenAPI specification and even by
scanning the .dll that contains the controllers, using
NSwagStudio
.
