Achraf Ben Alaya
No Result
View All Result
  • Home
  • News
  • Blog
    • blazor
    • c#
    • Cloud
      • Azure
    • docker
    • sql
    • xamarin
    • Dapr
    • Tricks, Tips and Fixes
    • General Tips & Fix
  • AI
  • Cloud
  • Motivation
  • Courses
  • About
    • Resume
    • Privacy Policy
SUBSCRIBE
  • Home
  • News
  • Blog
    • blazor
    • c#
    • Cloud
      • Azure
    • docker
    • sql
    • xamarin
    • Dapr
    • Tricks, Tips and Fixes
    • General Tips & Fix
  • AI
  • Cloud
  • Motivation
  • Courses
  • About
    • Resume
    • Privacy Policy
No Result
View All Result
Achraf Ben Alaya
No Result
View All Result
ADVERTISEMENT
Home Blog

Swagger & OpenAPI and Versioning for ASP.NET Core

achraf by achraf
December 8, 2020
in Blog, c#
4 min read
0
Swagger & OpenAPI and Versioning for ASP.NET Core
0
SHARES
1.5k
VIEWS
Share on FacebookShare on Twitter

Introduction

When you create a new .Netcore web API project ,you need to present and define in a very easy way to read .
In this case , Swagger is the solution .

Swagger is an Interface Description Language for describing RESTful APIs expressed using JSON. Swagger is used together with a set of open-source software tools to design, build, document, and use RESTful web services. Swagger includes automated documentation, code generation, and test-case generation.

Adding Swagger to a Web Api Core 3.1 project

You can add swagger to the project by installing the following NuGet package :

Swashbuckle.AspNetCore

Swagger Configuration

Sometimes configuring a nuget package can be hard and time wasting , but this not the case with swagger .

First we are going to  open Startup.cs and add Swagger service inside ConfigureServices

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

 

After that we are going to enable  Swagger in Configure() method :

 

app.UseSwagger();
         app.UseSwaggerUI(c => {

             c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");

         });

 

Now as I mentioned in the demo , we need to configure the launch browser in Debug from the properties of the solution :

 

Now, when we are going to start a new debugging session, we will be redirected to :

http://localhost:[yourportnumber]/swagger

Now , everything done if you are going to have one version of the API ,next we are going to see how to create different versions.

Versioning

When we update the API major version whenever we introduce breaking changes. Internally, we update minor and patch versions whenever we add functionality and backward-compatible updates. When we release a new major version of the an API clients can choose to either continue using an existing major version or migrate to the new one , so different versions must be present .

Changes that we need to do in Startup.cs :

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.HttpsPolicy;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.OpenApi.Models;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

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

        public IConfiguration Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();

            //Register the Swagger generator, defining 1 or more Swagger documents
            //services.AddSwaggerGen(c =>
            //{
            //    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
            //});

            services.AddControllers(options =>
            {
                options.Conventions.Add(new GroupingByNamespaceConvention());
            });

            services.AddSwaggerGen(config =>
            {
                var titlebase = "Ytdemo1";
                var desc = "Description";
                var termsofservice = new Uri("https://achrafbenalaya-ekgvbjdjgta4b4hz.francecentral-01.azurewebsites.net/");
                var license = new OpenApiLicense()
                {
                    Name = "MIT"
                };

                var contact = new OpenApiContact()
                {
                    Name = "achraf",
                    Email = "achrafbenalaya@gmail.com",
                    Url = new Uri("https://achrafbenalaya-ekgvbjdjgta4b4hz.francecentral-01.azurewebsites.net/")

                };


                config.SwaggerDoc("v1", new OpenApiInfo
                {
                    Version = "v1",
                    Title = titlebase + " V 1",
                    Description = desc,
                    Contact = contact,
                    License = license,
                    TermsOfService = termsofservice


                });

                config.SwaggerDoc("v2", new OpenApiInfo
                {
                    Version = "v2",
                    Title = titlebase + " V2",
                    Description = desc,
                    Contact = contact,
                    License = license,
                    TermsOfService = termsofservice


                });

            }

      );





        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }


            app.UseSwagger();
            app.UseSwaggerUI(c => {

                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
                c.SwaggerEndpoint("/swagger/v2/swagger.json", "My API V2");

            });



            app.UseHttpsRedirection();

            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }
    }
}

 

Now we need to add a convention to let swagger understand the different API version’s :

public class GroupingByNamespaceConvention : IControllerModelConvention
 {
     public void Apply(ControllerModel controller)
     {
         var controllerNamespace = controller.ControllerType.Namespace;
         var apiVersion = controllerNamespace.Split(".").Last().ToLower();
         if (!apiVersion.StartsWith("v")) { apiVersion = "v1"; }
         controller.ApiExplorer.GroupName = apiVersion;
     }
 }

 

Now we must apply the convention. For that we need to go to Startup.cs  ,look for ConfigureServices() and add the convention:

services.AddControllers(options =>
{
options.Conventions.Add(new GroupingByNamespaceConvention());
});

 

Project Link

Full Demos:

Swagger
ShareTweet
Previous Post

Kubernetes is deprecating Docker runtime support !

Next Post

FIX – YouTube Thumbnail Not Showing on Facebook

Related Posts

AI

Model Context Protocol (MCP): The Future of AI Integration

April 21, 2025
133
Azure

Step-by-Step Guide: Azure Front Door + Storage Account Static Website + Custom Domain with Terraform

March 11, 2025
272
Network Security & Route Tables – Checking NSGs, route tables, and service endpoints for a targeted VNET or Subnet
Azure

Network Security & Route Tables – Checking NSGs, route tables, and service endpoints for a targeted VNET or Subnet

February 3, 2025
141
Understanding Generative AI and RAG Benefits
AI

Understanding Generative AI and RAG Benefits

January 12, 2025
98
Azure Communication Services Email Sending Simplified: From Setup to Execution and Monitoring
Azure

Azure Communication Services Email Sending Simplified: From Setup to Execution and Monitoring

December 8, 2024
1.6k
PowerShell Automation for Azure Networks: Detailed VNET and Subnet Analysis
Azure

PowerShell Automation for Azure Networks: Detailed VNET and Subnet Analysis

November 2, 2024
508
Next Post
Configure Azure Web App Logging With .NET 5

Configure Azure Web App Logging With .NET 5

Leave a Reply Cancel reply

Your email address will not be published. Required fields are marked *

Terraform

Certifications

Microsoft certified trainer (MCT)

Recommended

Hello Microsoft Graph !

Hello Microsoft Graph !

February 25, 2021
526
Where is my Money ! The Proper way To Shutdown Azure VM

Where is my Money ! The Proper way To Shutdown Azure VM

November 2, 2020
860
Configuring Self-hosted Agent In Azure DevOps Pipeline

Configuring Self-hosted Agent In Azure DevOps Pipeline

April 13, 2023
1.2k

Step-by-Step Guide: Azure Front Door + Storage Account Static Website + Custom Domain with Terraform

March 11, 2025
272
How To Send Mail Using SQL Server

How To Send Mail Using SQL Server

April 20, 2020
296
Streamlining Website Editing on My Local Machine with Docker Compose and WordPress

Streamlining Website Editing on My Local Machine with Docker Compose and WordPress

July 1, 2023
151
Facebook Twitter LinkedIn Youtube

Model Context Protocol (MCP): The Future of AI Integration

April 21, 2025

Step-by-Step Guide: Azure Front Door + Storage Account Static Website + Custom Domain with Terraform

March 11, 2025
Network Security & Route Tables – Checking NSGs, route tables, and service endpoints for a targeted VNET or Subnet

Network Security & Route Tables – Checking NSGs, route tables, and service endpoints for a targeted VNET or Subnet

February 3, 2025

Categories

  • AI (2)
  • Apps (1)
  • Azure (63)
  • blazor (2)
  • Blog (91)
  • c# (7)
  • Cloud (65)
  • Courses (3)
  • Dapr (4)
  • docker (4)
  • Games (1)
  • General Tips & Fix (1)
  • Home (1)
  • Kubernetes Service (AKS) (1)
  • motivation (2)
  • Motivation (3)
  • News (9)
  • Resume (1)
  • sql (4)
  • Terrafrom (1)
  • Tricks, Tips and Fixes (4)
  • xamarin (5)
No Result
View All Result
  • Home
  • News
  • Blog
    • blazor
    • c#
    • Cloud
      • Azure
    • docker
    • sql
    • xamarin
    • Dapr
    • Tricks, Tips and Fixes
    • General Tips & Fix
  • AI
  • Cloud
  • Motivation
  • Courses
  • About
    • Resume
    • Privacy Policy