A Guide to OpenAPI Client Generation with Kiota. Deep dive (Part 2) dotnet aspnetcore openapi
A Guide to OpenAPI Client Generation with Kiota. Introduction (Part 1) dotnet aspnetcore openapi
What's new in .NET 6 and C# 10. Everything you wanted to know. dotnet csharp coding-stories
An opinionated look at Minimal API in .NET 6 dotnet aspnetcore coding-stories

TL;DR

OpenAPI is de facto standard that you should use to increase explorability of your ASP.NET Core projects.


Previously, I blogged about the tool https://codingstories.io/ to share step-by-step guides and real programming experience in general. In this blog post, you will find a coding story that describes the process of adding OpenAPI support to a ASP.NET Core project.

OpenAPI is great and you should definitely consider it. From this point, please navigate to the actual coding story how-to-add-openapi-to-aspnetcore, it is supposed to be self-contained and easy to understand. I’ll see you there!

https://gitlab.com/codingstories/how-to-add-openapi-to-aspnetcore

openapi-banner

Sneak peek the result

By the end of the coding story, you will see something like following:

public class Startup
{
   public void ConfigureServices(IServiceCollection services)
   {
      services.AddControllers();
      services.AddApiVersioning(options =>
      {
            options.ReportApiVersions = true;
            options.DefaultApiVersion = new ApiVersion(2, 0);
            options.AssumeDefaultVersionWhenUnspecified = true;
      });
      services.AddSwaggerGen(options =>
      {
            options.SwaggerDoc("v1", new OpenApiInfo()
            {
               Title = "Sample API",
               Version = "v1",
               Description = "A sample application with Swagger, Swashbuckle, and API versioning.",
               Contact = new OpenApiContact() { Name = "Sample User", Email = "sample@user.com" },
               License = new OpenApiLicense() { Name = "MIT", Url = new Uri("https://opensource.org/licenses/MIT") }
            });

            options.SwaggerDoc("v2", new OpenApiInfo()
            {
               Title = "Sample API",
               Version = "v2",
               Description = "A sample application with Swagger, Swashbuckle, and API versioning.",
               Contact = new OpenApiContact() { Name = "Sample User", Email = "sample@user.com" },
               License = new OpenApiLicense() { Name = "MIT", Url = new Uri("https://opensource.org/licenses/MIT") }
            });

            options.OperationFilter<SwaggerDefaultValues>();

      });
      services.AddVersionedApiExplorer(options =>
      {
            // Add the versioned api explorer, which also adds IApiVersionDescriptionProvider service
            // Note: the specified format code will format the version as "'v'major[.minor][-status]"
            options.GroupNameFormat = "'v'VVV";
      });
   }

   public void Configure(
      IApplicationBuilder app,
      IWebHostEnvironment env,
      IApiVersionDescriptionProvider apiVersionDescriptionProvider)
   {
      if (env.IsDevelopment())
      {
            app.UseDeveloperExceptionPage();
      }

      app.UseRouting();

      app.UseEndpoints(endpoints => endpoints.MapControllers());
      app.UseSwagger();
      app.UseSwaggerUI(c =>
      {
            foreach (var description in apiVersionDescriptionProvider.ApiVersionDescriptions.Reverse())
            {
               c.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json",
                  description.GroupName.ToUpperInvariant());
            }
            c.RoutePrefix = string.Empty;
      });
   }

   static string XmlCommentsFilePath
   {
      get
      {
            var basePath = PlatformServices.Default.Application.ApplicationBasePath;
            var fileName = typeof(Startup).GetTypeInfo().Assembly.GetName().Name + ".xml";
            return Path.Combine(basePath, fileName);
      }
   }
}

Please let me know what you think about this coding story. A feedback is very much appreciated 👍.

Reference


Oleksii Nikiforov

Jibber-jabbering about programming and IT.