Get started with Swagger(OpenAPI) and ASP.NET Core

When consuming a Web API, understanding its various methods can be challenging for a developer. Swagger, also known as OpenAPI, solves the problem of generating useful documentation and help pages for Web APIs. It provides benefits such as interactive documentation, client SDK generation, and API discoverability.

Support me

If you have found this project helpful, either as a library that you use or as a learning tool, please consider buying me a coffee:

Add Swashbuckle.AspNetCore

Install-Package Swashbuckle.AspNetCore -Version 5.0.0

Add and configure Swagger middleware

Net Core 3.1

publicvoidConfigureServices(IServiceCollectionservices){services.AddDbContext<TodoContext>(opt =>opt.UseInMemoryDatabase("TodoList"));services.AddControllers();// Register the Swagger generator, defining 1 or more Swagger documentsservices.AddSwaggerGen(c =>{c.SwaggerDoc("v1",newOpenApiInfo{Title="My API",Version="v1"});});}

In the Startup.Configure method, enable the middleware for serving the generated JSON document and the Swagger UI:

publicvoidConfigure(IApplicationBuilderapp){// Enable middleware to serve generated Swagger as a JSON endpoint.app.UseSwagger();// Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),// specifying the Swagger JSON endpoint.app.UseSwaggerUI(c =>{c.SwaggerEndpoint("/swagger/v1/swagger.json","My API V1");});app.UseRouting();app.UseEndpoints(endpoints =>{endpoints.MapControllers();});}

To serve the Swagger UI at the app's root (http://localhost:<port>/), set the RoutePrefix property to an empty string:

app.UseSwaggerUI(c =>{c.SwaggerEndpoint("/swagger/v1/swagger.json","My API V1");c.RoutePrefix=string.Empty;});

API info and description

The configuration action passed to the AddSwaggerGen method adds information such as the author, license, and description:

// Register the Swagger generator, defining 1 or more Swagger documentsservices.AddSwaggerGen(c =>{c.SwaggerDoc("v1",newOpenApiInfo{Version="v1",Title="Open API",Description="A simple example ASP.NET Core Web API",TermsOfService=newUri("https://example.com/terms"),Contact=newOpenApiContact{Name="Andre Mendonca",Email=string.Empty,Url=newUri("https://twitter.com/spboyer"),},License=newOpenApiLicense{Name="Use under LICX",Url=newUri("https://example.com/license"),}});});

// --------------------------------------------------------------------------------------------------------------------// <copyright file="Program.cs" company="Andre Mendonca">// Andre Mendonca// 3/7/2020// </copyright>// <summary>// Defines the Program type.// </summary>// --------------------------------------------------------------------------------------------------------------------namespaceOpenAPI{usingMicrosoft.AspNetCore.Hosting;usingMicrosoft.Extensions.Hosting;/// <summary>/// The program./// </summary>publicclassProgram{/// <summary>/// The main./// </summary>/// <param name="args">/// The args./// </param>publicstaticvoidMain(string[]args){CreateHostBuilder(args).Build().Run();}/// <summary>/// The create host builder./// </summary>/// <param name="args">/// The args./// </param>/// <returns>/// The <see cref="IHostBuilder"/>./// </returns>publicstaticIHostBuilderCreateHostBuilder(string[]args)=>Host.CreateDefaultBuilder(args).ConfigureWebHostDefaults(webBuilder =>{webBuilder.UseStartup<Startup>();});}}