Swagger/OpenAPI for Documentation in ASP.NET Core API

Swagger (also known as OpenAPI) is an open-source framework that helps you design, build, document, and consume RESTful APIs. Swagger provides a user-friendly interface for developers to interact with the API and automatically generates API documentation. In this page, we will discuss how to use Swagger/OpenAPI for documentation in ASP.NET Core API.

Heading h1

Swagger/OpenAPI for Documentation in ASP.NET Core API

Syntax

Swagger/OpenAPI implementation in ASP.NET Core API requires adding the Swashbuckle.AspNetCore NuGet package to your project. Once you have installed the NuGet package, add the following code to the ConfigureServices method in the Startup.cs file:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "API Title", Version = "v1" });
});

This code configures Swagger and sets the API title and version. Next, add the following code to the Configure method:

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "API Title");
});

This code adds Swagger middleware to generate a user-friendly interface that can be accessed through localhost:<port>/swagger and sets the endpoint for the API documentation.

Example

Here's an example of how to use Swagger/OpenAPI for documentation in ASP.NET Core API:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;
using System;

namespace MyAPI
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
            });
        }

        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                app.UseHsts();
            }

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

            app.UseHttpsRedirection();
            app.UseMvc();
        }
    }
}

Output

Swagger generates a user-friendly interface that can be accessed through localhost:<port>/swagger. This interface allows users to interact with the API and view automatically generated API documentation.

Explanation

Swagger/OpenAPI simplifies the documentation process by automatically generating documentation from your code's comments. This feature saves time and ensures that the generated documentation is up-to-date with the code.

Use

Using Swagger/OpenAPI for documentation in ASP.NET Core API makes it easy to create and update API documentation. It also helps developers interact with the API and troubleshoot any issues. Additionally, Swagger documentation can be used to build client libraries or to test your API with other tools.

Important Points

• To use Swagger/OpenAPI in ASP.NET Core API, you need to install the Swashbuckle.AspNetCore NuGet package.
• Swagger requires XML documentation to be enabled in your project's build settings.
• Swagger generates a user-friendly interface for the API, which can be accessed at localhost:<port>/swagger.

Summary

Swagger/OpenAPI is an essential tool for documentation in ASP.NET Core API. By installing the Swashbuckle.AspNetCore NuGet package and configuring the Startup.cs file, you can generate an interactive user interface and automatically generated documentation for your API.