www.dntips.ir
مطالب ۳۶۹۴
نویسندگان ۲۷۶
گروه‌های مطالب ۱۰۲۴
نقشه‌های راه ۱۱۹
دوره‌ها ۱۴
اشتراک‌ها ۱۷۹۱۴
عنوان:

‫مستندسازی خودکار API ها در برنامه‌های مبتنی بر ASP.NET Core بوسیله‌ی Swagger


نویسنده: حامد شیربندی
تاریخ: ۱۳۹۷/۰۶/۲۹ ۲۱:۵۰
آدرس: www.dntips.ir
پیشتر مطلبی در این زمینه در سایت منتشر شد که به خوبی نحوه‌ی پیاده سازی Swagger را در یک برنامه‌ی ASP.NET Web API نشان می‌دهد. حال در این مقاله‌ی کوتاه میخواهیم نحوه‌ی پیاده سازی آن را در یک برنامه‌ی مبتنی بر ASP.NET Core بررسی کنیم.

دریافت Swagger از نوگت

ابتدا باید این پکیج را از آدرسش در نیوگت بگیریم و در برنامه‌ی خود نصب کنیم:
pm> Install-Package Swashbuckle.AspNetCore

پیکربندی برنامه 

برای کانفیگ Swagger و تولید خودکار و پویای مستندات API‌ها توسط آن باید تنظیمات زیر را در کلاس Startup برنامه انجام دهیم :
using Microsoft.AspNetCore.Mvc;
using Swashbuckle.AspNetCore.Swagger;

namespace MyProject.Web.Api
{
    public class Startup
    {
        public IServiceProvider ConfigureServices(IServiceCollection services)
        {  
            // Register the Swagger generator, defining one or more Swagger documents
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info { Title = "MyProject API Documentation", Version = "v1" });
            });  
        }

        public void Configure(IApplicationBuilder app, IHostingEnvironment env, IServiceScopeFactory serviceScopeFactory)
        {
            // Enable middleware to serve generated Swagger as a JSON endpoint.
            app.UseSwagger();

            // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), specifying the Swagger JSON endpoint.
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
            });           
        }
    }
}

مشاهده خروجی مستند سازی API ها

بعد از اینکه کانفیگ‌های فوق را انجام دادیم کافی است تا برنامه را اجرا کرده و آدرس زیر را در مرورگر وارد کنیم:
http://localhost:port/swagger
 در این صورت خروجی به شکل زیر نمایش داده خواهد شد که حاوی اطلاعات بسیار مفیدی در مورد API‌ها می‌باشد. اطلاعاتی شامل http method ، آدرس API، پارامترهای ورودی، مدل خروجی و ...
در صورت استفاده از SWagger ، ذکر [HttpGet]  برای API‌های GET اجباری می‌شود و در صورتیکه این مورد را برای API ای مشخص نکرده باشیم با خطای Run Time مواجه شده و برنامه اجرا نخواهد شد. 

 

مطالب مشابه

نظرات

  • محمد احمدی نیا در ۱۳۹۷/۰۷/۰۳ ۱۶:۴۴
    یک نکته تکمیلی
    جهت لود کردن description‌های هر action و controller در لایبرری swagger بدین شکل می‌توان عمل کرد.
    services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1",
                    Title = "My API",
                    Description = "My Web API",
                    TermsOfService = "None",
                    Contact = new Contact
                    {
                        Name = "Mohammad Ahmadi",
                        Email = string.Empty,
                        Url = "https://www.dntips.ir"
                    },
                    License = new License
                    {
                        Name = "Use under LICX",
                        Url = "https://example.com/license"
                    }
                });
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                c.IncludeXmlComments(xmlPath);
            });
    مقادیر description‌ها باید درون یک فایل xml ایجاد شوند تا توسط swagger قابل بارگذاری باشند، بدین ترتیب روی پروژه در Solution Explorer راست کلیک کرده گزینه Edit را انتخاب کنید سپس تکه کد زیر را اضافه کنید.  
    <PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>
    در این صورت برای متدهایی که بالای آنها از xml استفاده نشود warning صادر میشود که برای رفع این مشکل کد بالا را به این صورت تغییر دهید
    <PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
  • احمد قاسمی در ۱۳۹۹/۰۹/۱۰ ۲۲:۲۱
    با سلام
    ضمن تشکر از حامد شیربندی عزیز
    این سطر باید اصلاح بشه:
     c.SwaggerDoc("v1", new Info { Title = "MyProject API Documentation", Version = "v1" });
    به این گونه :
    c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo{ Title = "MyProject API Documentation", Version = "v1" });