پیشتر
مطلبی در این زمینه در سایت منتشر شد که به خوبی نحوهی پیاده سازی 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 مواجه شده و برنامه اجرا نخواهد شد.