This post is an overview of how to install and configure Swagger for .NET Core. If you are searching for tips & tricks, you might be interested in the article: Swagger in .NET Core: Tips & Tricks.
What is Swagger
Swagger is an open-source software framework backed by a large ecosystem of tools that helps developers design, build, document, and consume RESTful web services. While most users identify Swagger by the Swagger UI tool, the Swagger toolset includes support for automated documentation, code generation, and test-case generation.
Some of these tools are:
- Swagger Editor: Swagger Editor lets you edit OpenAPI specifications in YAML inside your browser and to preview documentations in real time.
- Swagger Codegen: Allows generation of API client libraries (SDK generation), server stubs and documentation automatically given an OpenAPI Spec.
- Swagger Inspector: API Inspection tool that lets you generate OpenAPI definitions from existing API
- SwaggerHub: API design and documentation, built for teams working with OpenAPI.
Swagger for .NET Core
Swagger for .NET Core comes by the name Swashbuckle.AspNetCore, and it is actually composed of three components which you can potentially install seperately:
- Swashbuckle.AspNetCore.Swagger: a Swagger object model and middleware to expose SwaggerDocument objects as JSON endpoints.
- Swashbuckle.AspNetCore.SwaggerGen: a Swagger generator that builds SwaggerDocument objects directly from your routes, controllers, and models. It’s typically combined with the Swagger endpoint middleware to automatically expose Swagger JSON.
- Swashbuckle.AspNetCore.SwaggerUI: an embedded version of the Swagger UI tool. It interprets Swagger JSON to build a rich, customizable experience for describing the web API functionality. It includes built-in test harnesses for the public methods.
Assuming you installed nuget packages before, installation is very easy! Just follow the next steps to install
Swashbuckle.AspNetCore nuget package from Visual Studio:
- Right click on the project you wish to install
- Click on “Manage Nuget Packages“
- Write “Swashbuckle” in the search
- Click on the correct(!) package, the one named
- Click “Install“
Getting started with swagger is extremely easy, since you just need to register the three components contained in the
If your project calls
AddApiExplorer()method must be explicitly called. Check the following link for more information, see Swashbuckle, ApiExplorer, and Routing.
First, add the Swagger generator to the services collection in the
And then in the
Startup.Configure method, enable the middleware for serving the generated JSON document and the Swagger UI:
Setting up swagger is very easy -you just follow the “Getting Started” guide above-, but swagger is so much more than that. If you want to find out how to setup an interactive documentation based on Swagger, along with some other tips and tricks, read the post “Swagger in .NET Core: Tips & Tricks“.