DEV Community

loading...
Cover image for How to add OpenAPI to ASP.NET Core project. A coding story.

How to add OpenAPI to ASP.NET Core project. A coding story.

Oleksii Nikiforov
Software Engineer at EPAM. Interested in .NET, TypeScript, Docker, table tennis, and good music.
Originally published at nikiforovall.github.io Updated on ・2 min read

TL;DR

OpenAPI is a 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 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!

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);
      }
   }
}
Enter fullscreen mode Exit fullscreen mode

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

Reference

Discussion (0)