پیاده سازی Swagger,ApiVersion در web api core 3

قبل از اینکه وارد بحث بشیم یک مقدمه ساده درباره دو Swagger , ApiVersion تشریح خواهیم کرد.

توجه!برای خواندن این مقاله باید با web api در asp core 3 اشنایی داشته باشید

؛ Swagger : وقتی شما یک وب سرویس رو مینویسید و میخوایید نحوره کار باهاش رو به کلاینت کار بدید چند روش وجود داره.کاری که بیشتر برنامه نویسا انجام میدن نوشتن داکیومت مربوط به وب سرویس ها همچنین نحوه فراخوانی ان در postman میباشد که روش معقول و پسندیده ای میباشد.

؛ postman یک برنامه قدرتمند برای فرخوانی ، تست و.. وب سرویس ها میباشد .شما میتوانید در این لینک به صورت کامل Postman رو مطالعه کنید.میتوانید بسته به سیستم عامل خود آن را دانلود کنید و همچنین میتوانید نسخه کروم ان رو بر رویه مرورگر خود نصب کنید ولی توسه میشود نسخه مربوط به سیستم عمل ان را نصب کنید

همانطور که گفته شد نوشتن داکیومت با Postman یک روش معقول میباشد و توسیه میشود حتما انجام داد!

ولی روش های دیگه ای وجود دارد که شما علاوه بر Postman میتوانید به پروژه خود اضافه کنید.کتاب خانه های مختلفی برای این کار وجود دارن که به راحتی میتوان نصب کرد

؛ swagger : یک کتاب خانه سورس باز میباشد که به راحتی رو پروژه نصب میشود و یک نما ساده و از وب سرویس ها نمایش میدهد.شما با Swagger برای هر وب سرویس خود میتوانید داکیومن بنویسید و نوع خروجی و ورودی ها رو نمایش بدید. نحوه نصب ان برای اکثر زبان های برنامه نویس موجود می باشد .

ما در این مقاله از asp core 3 استفاده میکنیم

نصب آن بر رویه asp core 3 بسیار ساده است و با نوشتن چند دستور ساده میتوانید آن را نصب کنید ولی ما میخوایم علاوه به Api Version ، Swagger هم داشته باشیم.

؛ Api Version : فرض کنید شما پروژتون Stable شده و کلاینت ها دارن استفاده میکنن ولی به هر دلیلی مثلا میخواید علاوه بر اپلیکشین اندروید فعلی یک اپلیکیشن دیگه با امکانات جدیدتر بزنید شما نباید به وب سرویس های فعلی خود دست بزنید و همزمان باید وب سرویس هارو ویرایش یا اضافه کنید!یک راه دیگه نوشتن یک پروژه جدید میباشد که از نظر کاری ممکنه زمان بر باشه و زیاد جالب نیست!

راه دیگه نوشتن api version برای وب سرویس هایمان است به این معنی وب سریس های فعلی باقی بمانند و شروع به توشتن وب سریس جدید با ورژن جدید بکنیم بدون اینکه تغیر در حالت فعلی به وجود بیاید.

توجه کنید api version را باید هنگام ساخت پروژه لحاظ کنید چون بعد از اینکه کلاینت کار از نسخه بدون ورژن استفاده کنند مشکل ساز خواهد بود که به ادرس جدید دیگه ای را فرواخوانی کنند

اگه شما از نسخه core 2 استفاده میتوانید از این مقاله به صورت کامل آن را پیاده سازی کنید ولی برای نسخه 3 باید طبق همین مقاله پیش برید.

برای شروع یک پروژه از نوع web api با دستور زیر ایجاد کنید

dotnet new webapi

پس از نصب با دستور dornet run از صحت اجرا پروژه مطمن شوید

وارد .csproj شوید و پکیج های زیر را نصب کنید هم.github

 <PackageReference Include=&quotMicrosoft.AspNetCore.Mvc.Versioning&quot Version=&quot3.0.0&quot />
<PackageReference Include=&quotSwashbuckle.AspNetCore&quot Version=&quot5.0.0-rc5&quot />

همچنین در فایل جاری تنظیمات زیر را انجام دهید.

 <Project Sdk=&quotMicrosoft.NET.Sdk.Web&quot>
<PropertyGroup>
<TargetFramework>netcoreapp3.1</TargetFramework>
<RootNamespace>Versioning_ASP.Net_Core_3_APIs_with_Swashbuckle</RootNamespace>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>
<ItemGroup>
<PackageReference Include=&quotMicrosoft.EntityFrameworkCore.Sqlite&quot Version=&quot3.1.0&quot />
<PackageReference Include=&quotMicrosoft.EntityFrameworkCore.SqlServer&quot Version=&quot3.1.0&quot />
<PackageReference Include=&quotMicrosoft.TypeScript.MSBuild&quot Version=&quot3.7.4&quot>
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
<PrivateAssets>all</PrivateAssets>
</PackageReference>
<PackageReference Include=&quotMicrosoft.AspNetCore.Mvc.Versioning&quot Version=&quot4.1.0&quot />
<PackageReference Include=&quotMicrosoft.AspNetCore.Mvc.NewtonsoftJson&quot Version=&quot3.1.0&quot />
<PackageReference Include=&quotMicrosoft.Extensions.Logging.Debug&quot Version=&quot3.1.0&quot />
<PackageReference Include=&quotMicrosoft.Extensions.PlatformAbstractions&quot Version=&quot1.1.0&quot />
<PackageReference Include=&quotMicrosoft.VisualStudio.Web.CodeGeneration.Design&quot Version=&quot3.1.0&quot />
<PackageReference Include=&quotNLog.Web.AspNetCore&quot Version=&quot4.9.0&quot />
<PackageReference Include=&quotSwashbuckle.AspNetCore&quot Version=&quot5.0.0-rc5&quot />
</ItemGroup>
</Project>

بعد با دستور زیر پکیج ها رو نصب کنید dotnet restore البته به محض ذخیره کردن به صورت اتوماتیک و پکیجا نصب میشن.

وارد پوشه Comtroller شوید و دو پوشه به نام v1 و v2 ایجاد کنید و همچنین درون هر پوشه دو کنترل با نام های ApiVersion بسازید.وارد پوشه v1 شوید و ApiController را به شکل زیر پیاده سازی کنید.github

[ApiVersion(&quot1&quot)]
[Route(&quotapi/v{version:apiVersion}/[controller]&quot)]
[ApiController]
public class ApiVersionController : ControllerBase
{
[HttpGet()]
public string Get() => &quotSpace Potatoes v1&quot
}

توجه کنید ما فقط یک Controller تستی ایجاد کردیم با یک متد که یک متن رشته ای رو برگشت میده

وارد د پوشه v2 شوید و ApiController را به شکل زیر پیاده سازی کنید.github

[ApiVersion(&quot2&quot)]
[Route(&quotapi/v{version:apiVersion}/[controller]&quot)]
[ApiController]
public class ApiVersionController:ControllerBase
{
[HttpGet()]
public string Get() => &quotSpace Potatoes v2&quot
}

برای اینکه بتوانیم به صورت داینامیک هر چند ورژنی که تمایل داشتیم داشته باشیم در Root پروژه یک پوشه به نام Swagger ساخته و دو کلاس زیر را در ان ایجاد کنید. RemoveVersionParameterOperationFilter

public class RemoveVersionParameterOperationFilter : IOperationFilter
  {
  public void Apply(OpenApiOperation operation, OperationFilterContext context)
        {
            // Remove version parameter from all Operations
            var versionParameter = operation.Parameters.Single(p => p.Name == &quotversion&quot);
            operation.Parameters.Remove(versionParameter);
        }
    }

؛ SetVersionInPathDocumentFilter

 public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
        {
            var updatedPaths = new OpenApiPaths();
            foreach (var entry in swaggerDoc.Paths)
            {
                updatedPaths.Add(
                    entry.Key.Replace(&quotv{version}&quot, swaggerDoc.Info.Version),
                    entry.Value);
            }
            swaggerDoc.Paths = updatedPaths;
        }

در نهایت وارد Startup شوید و به صورت زیر آن را کانفیگ کنید

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();
             services.AddApiVersioning(o =>
            {
                o.ReportApiVersions = true;
                o.AssumeDefaultVersionWhenUnspecified = true;
                o.DefaultApiVersion = new ApiVersion(1, 0);
            });
 
            services.AddSwaggerGen(option =>
            {
                option.SwaggerDoc(&quotWithsaltWebApiDemo&quot, new OpenApiInfo
                {
                    Version = &quotv1&quot,
                    Title = &quotWithsaltWebApiDemo API&quot,
                    Description = &quotAPI for WithsaltWebApiDemo&quot,
                    Contact = new OpenApiContact() { Name = &quotwithsalt&quot, Email = &quotwithsalt@geeiot.net&quot }
                });


                option.SwaggerDoc(&quotv1&quot, new OpenApiInfo { Version = &quotv1&quot, Title = &quotAPI V1&quot });
                option.SwaggerDoc(&quotv2&quot, new OpenApiInfo { Version = &quotv2&quot, Title = &quotAPI V2&quot });


                option.DocInclusionPredicate((docName, apiDesc) =>
                {
                    var versions = apiDesc.CustomAttributes()
                        .OfType<ApiVersi>()
                        .SelectMany(attr => attr.Versions);


                    return versions.Any(v => $&quotv{v.ToString()}&quot == docName);
                });


                option.OperationFilter<RemoveVersionParameterOperationFilter>();
                option.DocumentFilter<SetVersionInPathDocumentFilter>();


                // include document file
                option.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, $&quot{typeof(Startup).Assembly.GetName().Name}.xml&quot), true);
                option.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, $&quotVersioning-ASP.Net-Core-3-APIs-with-Swashbuckle.xml&quot), true);
            });


            services.AddControllers()
                .AddNewtonsoftJson(options =>
                {
                    options.SerializerSettings.ContractResolver = new DefaultContractResolver();
                });
        }


        // 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.UseDeveloperExcepti();
            }
            app.UseHttpsRedirection();
            app.UseRouting();
            app.UseAuthorization();
            app.UseEndpoints(endpoints =>{endpoints.MapControllers();});
            app.UseStaticFiles();
             app.UseSwagger();
            //Enable middleware to serve swagger-ui (HTML, JS, CSS etc.), specifying the Swagger JSON endpoint
            app.UseSwaggerUI(option =>
            {
                option.SwaggerEndpoint(&quot/swagger/v2/swagger.json&quot, &quotV2 Docs&quot);
                option.SwaggerEndpoint(&quot/swagger/v1/swagger.json&quot, &quotV1 Docs&quot);


                option.RoutePrefix = string.Empty;
                option.DocumentTitle = &quotWithsaltWebApiDemo API&quot
            });
        }
}

اکنون یک بار دیگر پروژه را اجرا کنید این بار خرجی به شکل زیر خواهد بود که در گوشه سمت راست بالا میتوانید ورژن وب سرویس های خودتون رو انتخاب کنید و بر رویه هر وب سرویس کلیک کنید میتوانید به سادگی ان را فرخوانی کنید

هدف این مقاله ورژن بندی در Swagger بود.شما میتوانید به یک سرچ ساده Swagger با به صورت پیشرفته تر کانفیگ کنید.

میتوان Swagger Version را به سادگی نصب کرد ولی مشکلی که خودم در چندین ساعت روش کار کردم این بود که تو نسخه Core 3 خیلی خطا زیادی داره هرچقد سرچ کردم اخرش با یک سایت چینی تونستم در ورژن 3 همه Api Version رو بالا بیارم

اگه از مقاله راضی بودید میتونید از لینک زیر برام قهوه بخرید : )