سفارشی کردن Swagger در توابع Azure

Swagger UI یک ابزار منبع باز است که به توسعه دهندگان اجازه می دهد تا API هایی را که در حال ساخت هستند تجسم کرده و با آنها تعامل داشته باشند. این یک رابط کاربر پسند فراهم می کند که به توسعه دهندگان اجازه می دهد منابع، پارامترها و پاسخ های API را بررسی کنند. Swagger UI به ویژه برای توسعه دهندگانی که می خواهند API های خود را قبل از استقرار آزمایش و اشکال زدایی کنند مفید است.
از توابع Azure می توان برای ساخت API های RESTful استفاده کرد، و آن را به یک انتخاب محبوب برای توسعه دهندگانی تبدیل می کند که می خواهند API های سبک وزن و مقیاس پذیر ایجاد کنند. Azure Functions همچنین پشتیبانی داخلی از Swagger UI را ارائه میکند و توسعهدهندگان را آسان میکند تا آن را به APIهای خود اضافه کنند.
بنابراین، بیایید شیرجه بزنیم!
بسته NuGet
می توانید از یک پروژه موجود یا از یک پروژه جدید Azure Function شروع کنید.
ابتدا باید بسته NuGet را به نام اضافه کنیم AzureExtensions.Swashbuckle.
این بسته واقعا به روز نیست اما همچنان کار می کند و تنها راه رسیدن به هدف ماست.
کلاس استارتاپ
وظیفه دوم اضافه کردن یک کلاس Startup به پروژه است.
یک کلاس خالی جدید ایجاد کنید و همه چیز را با کد زیر جایگزین کنید.
[assembly: FunctionsStartup(typeof(Startup))]
namespace FunctionApp1
{
public class Startup : FunctionsStartup
{
public override void Configure(IFunctionsHostBuilder builder)
{
builder.AddSwashBuckle(Assembly.GetExecutingAssembly(), opts =>
{
opts.SpecVersion = OpenApiSpecVersion.OpenApi2_0;
opts.AddCodeParameter = true;
opts.PrependOperationWithRoutePrefix = true;
opts.Documents = new[]
{
new SwaggerDocument
{
Name = "v1",
Title = "My API Documentation",
Description = "a long description of my APIs",
Version = "v1"
}
};
opts.Title = "Swagger Test";
opts.ConfigureSwaggerGen = (x =>
{
x.CustomOperationIds(apiDesc =>
{
return apiDesc.TryGetMethodInfo(out MethodInfo methodInfo)
? methodInfo.Name
: new Guid().ToString();
});
});
});
}
}
}
واضح است، اما می توانید مقادیر ویژگی های کلاس Swagger Document را تغییر دهید.
نقاط پایانی UI Swagger
اکنون زمان آن رسیده است که پاسخ دو نقطه پایانی اصلی را برای Swagger لغو کنیم.
برای انجام این کار، می توانید یک کلاس خالی جدید ایجاد کنید و کد زیر را داخل آن قرار دهید.
این کد به سادگی صفحات Swagger پیش فرض را با صفحات جدید جایگزین می کند.
public static class SwaggerController
{
[SwaggerIgnore]
[FunctionName("Swagger")]
public static Task<HttpResponseMessage> Run(
[HttpTrigger(AuthorizationLevel.Function, "get", Route = "Swagger/json")] HttpRequestMessage req,
[SwashBuckleClient] ISwashBuckleClient swashBuckleClient)
{
return Task.FromResult(swashBuckleClient.CreateSwaggerJsonDocumentResponse(req));
}
[SwaggerIgnore]
[FunctionName("SwaggerUi")]
public static Task<HttpResponseMessage> Run2(
[HttpTrigger(AuthorizationLevel.Function, "get", Route = "Swagger/ui")] HttpRequestMessage req,
[SwashBuckleClient] ISwashBuckleClient swashBuckleClient)
{
return Task.FromResult(swashBuckleClient.CreateSwaggerUIResponse(req, "swagger/json"));
}
}
صفحه جدید را مشاهده کنید
اکنون شما آماده دیدن نتیجه تغییرات ما هستید.
پروژه Azure Function را در اشکال زدایی یا بدون اشکال زدایی راه اندازی کنید و به مسیر “{hostname}/api/swagger/ui“.
باید صفحه Swagger UI را با اطلاعات جدید مشاهده کنید.
آیا علاقه مند به یادگیری GitHub هستید اما نمی دانید از کجا شروع کنید؟ دوره آموزشی من در LinkedIn Learning: Learning GitHub را امتحان کنید.
با تشکر از خواندن این پست، امیدوارم برای شما جالب بوده باشد!
با خیال راحت من را دنبال کنید تا در صورت انتشار مقالات جدید مطلع شوید 🙂
