Achraf Ben Alaya
No Result
View All Result
  • Home
  • News
  • Blog
    • blazor
    • c#
    • Cloud
      • Azure
    • docker
    • sql
    • xamarin
    • Dapr
    • Tricks, Tips and Fixes
  • Cloud
  • Motivation
  • General Tips & Fix
  • About
    • Resume
SUBSCRIBE
  • Home
  • News
  • Blog
    • blazor
    • c#
    • Cloud
      • Azure
    • docker
    • sql
    • xamarin
    • Dapr
    • Tricks, Tips and Fixes
  • Cloud
  • Motivation
  • General Tips & Fix
  • About
    • Resume
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.2k
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("http://achrafbenalaya.com/");
                var license = new OpenApiLicense()
                {
                    Name = "MIT"
                };

                var contact = new OpenApiContact()
                {
                    Name = "achraf",
                    Email = "achrafbenalaya@gmail.com",
                    Url = new Uri("http://achrafbenalaya.com/")

                };


                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

Configuring GitHub Advanced Security for Azure DevOps: A Must-Have in Today’s DevOps Landscape
Azure

Configuring GitHub Advanced Security for Azure DevOps: A Must-Have in Today’s DevOps Landscape

September 28, 2023
28
The Significance of Azure DevSecOps: Best Practices for Securing Your Pipelines
Azure

The Significance of Azure DevSecOps: Best Practices for Securing Your Pipelines

August 17, 2023
131
Navigating the Alphabet Soup: Unraveling Microsoft Acronyms
Azure

Navigating the Alphabet Soup: Unraveling Microsoft Acronyms

July 16, 2023
54
Streamlining Website Editing on My Local Machine with Docker Compose and WordPress
Blog

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

July 1, 2023
40
Block the default URL assigned to the azure web app using azure application gateway
Azure

Block the default URL assigned to the azure web app using azure application gateway

May 31, 2023
142
Block the default URL assigned to the azure web app
Blog

Block the default URL assigned to the azure web app

May 14, 2023
484
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

The Significance of Azure DevSecOps: Best Practices for Securing Your Pipelines

The Significance of Azure DevSecOps: Best Practices for Securing Your Pipelines

August 17, 2023
131
Access Microsoft Azure Courses On Pluralsight for Free

Access Microsoft Azure Courses On Pluralsight for Free

April 21, 2020
320
405 method not allowed in IIS

405 method not allowed in IIS

October 17, 2020
4.4k
Configure postman / newman API tests in Azure DevOps

Configure postman / newman API tests in Azure DevOps

October 25, 2021
2.9k
Generating report for SSL Certificates for Websites with PowerShell

Generating report for SSL Certificates for Websites with PowerShell

April 10, 2022
851
Azure Tips

Azure Tips

April 28, 2020
342
Facebook Twitter LinkedIn Youtube
Configuring GitHub Advanced Security for Azure DevOps: A Must-Have in Today’s DevOps Landscape

Configuring GitHub Advanced Security for Azure DevOps: A Must-Have in Today’s DevOps Landscape

September 28, 2023
The Significance of Azure DevSecOps: Best Practices for Securing Your Pipelines

The Significance of Azure DevSecOps: Best Practices for Securing Your Pipelines

August 17, 2023
Navigating the Alphabet Soup: Unraveling Microsoft Acronyms

Navigating the Alphabet Soup: Unraveling Microsoft Acronyms

July 16, 2023

Categories

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