‫مستند سازی ASP.NET Core 2x API توسط OpenAPI Swagger – قسمت هفتم – سفارشی سازی ظاهر مستندات API


‫مستند سازی ASP.NET Core 2x API توسط OpenAPI Swagger – قسمت هفتم – سفارشی سازی ظاهر مستندات API

امکان کنترل کامل و سفارشی سازی ظاهر نهایی Swagger-UI وجود دارد که جزئیات آن‌را در این قسمت بررسی خواهیم کرد. بهبود ظاهر کامنت‌ها با بکارگیری Markdown Markdown زبان سبکی است برای تعیین شیوه‌نامه‌ی نمایش متون ساده. اگر پیشتر با سیستم ارسال نظرات Github و یا Stackoverflow کار کرده باشید، قطعا با آن آشنایی دارید. توضیحات کامل و جزئیات آن‌را...

امکان کنترل کامل و سفارشی سازی ظاهر نهایی Swagger-UI وجود دارد که جزئیات آن‌را در این قسمت بررسی خواهیم کرد.

بهبود ظاهر کامنت‌ها با بکارگیری Markdown

Markdown زبان سبکی است برای تعیین شیوه‌نامه‌ی نمایش متون ساده. اگر پیشتر با سیستم ارسال نظرات Github و یا Stackoverflow کار کرده باشید، قطعا با آن آشنایی دارید. توضیحات کامل و جزئیات آن‌را می‌توانید در آدرس markdownguide.org مطالعه کنید. خوشبختانه امکان استفاده‌ی از Markdown در OpenAPI spec نیز وجود دارد که سبب بهبود ظاهر مستندات نهایی حاصل از آن خواهد شد.

در قسمت سوم، سعی کردیم مثالی را توسط remarks، به قسمت Patch اضافه کنیم که ظاهر آن، آنچنان مطلوب به نظر نمی‌رسد و بهتر است آن‌را به صورت یک قطعه کد نمایش داد:

‫مستند سازی ASP.NET Core 2x API توسط OpenAPI Swagger – قسمت هفتم – سفارشی سازی ظاهر مستندات API

برای بهبود این ظاهر می‌توان از Markdown استفاده کرد. بنابراین ابتدا تمام backslash‌های اضافه شده را که جهت نمایش خطوط جدید اضافه شده بودند، حذف می‌کنیم. در Markdown خطوط جدید با درج حداقل ۲ فاصله (space) و یک سطر جدید مشخص می‌شوند. همچنین استفاده‌ی از ** سبب ضخیم شدن نمایش عبارت‌ها می‌شود. برای اینکه قطعه کد نوشته شده را در Markdown به صورت کدی با پس زمینه‌ای مشخص نمایش دهیم، پیش از شروع هر سطر آن نیاز است یک tab و یا ۴ فاصله (space) درج شوند:

/// /// Sample request (this request updates the author's **first name**) /// /// PATCH /authors/id /// [ /// { /// "op": "replace", /// "path": "/firstname", /// "value": "new first name" /// } /// ] ///

پس از این تغییرات خواهیم داشت:

‫مستند سازی ASP.NET Core 2x API توسط OpenAPI Swagger – قسمت هفتم – سفارشی سازی ظاهر مستندات API

که نسبت به حالت قبلی بسیار بهتر به نظر می‌رسد.

در نگارش فعلی، استفاده‌ی از Markdown برای توضیحات remarks، پارامترها و response codes پشتیبانی می‌شود؛ اما نه برای قسمت summary که برای نگارش بعدی درنظر گرفته شده‌است. همچنین از قابلیت‌های پیشترفته‌ی Markdown هم استفاده نکنید (در کل نیاز به مقداری سعی و خطا دارد تا مشخص شود چه قابلیت‌هایی را پشتیبانی می‌کند).

سفارشی سازی مقدماتی UI به کمک تنظیمات API آن

جائیکه تنظیمات میان‌افزار Swashbuckle.AspNetCore در کلاس Starup تعریف می‌شوند، می‌توان تغییراتی را نیز در UI آن اعمال کرد:

namespace OpenAPISwaggerDoc.Web { public class Startup { public void Configure(IApplicationBuilder app, IHostingEnvironment env) { // ... app.UseSwaggerUI(setupAction => { setupAction.SwaggerEndpoint( url: "/swagger/LibraryOpenAPISpecification/swagger.json", name: "Library API"); setupAction.RoutePrefix = ""; setupAction.DefaultModelExpandDepth(2); setupAction.DefaultModelRendering(Swashbuckle.AspNetCore.SwaggerUI.ModelRendering.Model); setupAction.DocExpansion(Swashbuckle.AspNetCore.SwaggerUI.DocExpansion.None); setupAction.EnableDeepLinking(); setupAction.DisplayOperationId(); }); // ... } } }

با این خروجی که به علت تنظیم DocExpansion آن به None، اینبار لیست قابلیت‌ها را به صورت باز شده نمایش نمی‌دهد:

‫مستند سازی ASP.NET Core 2x API توسط OpenAPI Swagger – قسمت هفتم – سفارشی سازی ظاهر مستندات API

همچنین چون DefaultModelRendering به Model تنظیم شده‌است، اینبار بجای مثال، مشخصات مدل را به صورت پیش‌فرض نمایش می‌دهد:

‫مستند سازی ASP.NET Core 2x API توسط OpenAPI Swagger – قسمت هفتم – سفارشی سازی ظاهر مستندات API

کار DisplayOperationId نمایش Id هر Operation است؛ مانند get_api_authors. در اینجا Operation همان مداخل API ما هستند و به عنوان هر قسمت، Tag گفته می‌شود؛ مانند Authors و یا Books:

‫مستند سازی ASP.NET Core 2x API توسط OpenAPI Swagger – قسمت هفتم – سفارشی سازی ظاهر مستندات API

با فعالسازی EnableDeepLinking، آدرس‌هایی مانند tagName/# و یا tagName/OperationId/# قابلیت مرور و بازشدن خودکار را پیدا می‌کنند (tagName همان نام کنترلر است و OperationId همان اکشن متدی که عمومی شده‌است). برای مثال اگر آدرس https://localhost:5001/index.html#/Books/get_api_authors__authorId__books را در یک برگه‌ی جدید مرورگر باز کنیم، بلافاصله گروه Books، باز شده و سپس به اکشن متد یا مدخلی که Id آن ذکر شده‌است، هدایت می‌شویم:

‫مستند سازی ASP.NET Core 2x API توسط OpenAPI Swagger – قسمت هفتم – سفارشی سازی ظاهر مستندات API

اعمال تغییرات پیشرفته در UI

Swagger-UI در اصل از یک سری فایل html، css، js و فونت تشکیل شده‌است که آن‌ها را می‌توانید در آدرس src/Swashbuckle.AspNetCore.SwaggerUI مشاهده کنید. برای مثال فایل index.html آن‌را در اینجا می‌توانید مشاهده کنید. اصل آن در div ای با id مساوی swagger-ui رخ می‌دهد و در این قسمت است که رابط کاربری آن به صورت پویا تولید شده و رندر خواهد شد. بررسی فایل‌های js و css آن در این مخزن کد مشکل است؛ چون نگارش فشرده شده‌ی آن هستند. به همین جهت می‌توان به مخزن کد اصلی Swagger-UI که نگارش جایگذاری شده‌ی آن (embedded) توسط Swashbuckle.AspNetCore ارائه می‌شود، رجوع کرد. برای مثال در پوشه‌ی src/styles آن، اصل فایل‌های css آن برای سفارشی سازی وجود دارند.

پس از اعمال تغییرات خود، می‌توانید css و یا js سفارشی خود را به نحو زیر به تنظیمات app.UseSwaggerUI سیستم معرفی کنید:

setupAction.InjectStylesheet("/Assets/custom-ui.css"); setupAction.InjectJavaScript("/Assets/custom-js.js");

باید دقت داشت که این فایل‌ها باید در پوشه‌ی wwwroot قرار گرفته و قابل دسترسی باشند.

برای اعمال تغییرات اساسی و تزریق صفحه‌ی index.html جدیدی، می‌توان به صورت زیر عمل کرد:

setupAction.IndexStream = () => GetType().Assembly.GetManifestResourceStream( "OpenAPISwaggerDoc.Web.EmbeddedAssets.index.html");

نکته‌ی مهم: اینبار این فایل باید به صورت embedded ارائه شود. به همین جهت در مثال فوق، عبارت OpenAPISwaggerDoc.Web به فضای نام اصلی اسمبلی جاری اشاره می‌کند. سپس EmbeddedAssets، نام پوشه‌ای است که فایل index.html سفارشی سازی شده، در آن قرار خواهد گرفت. اکنون برای اینکه این فایل را به صورت EmbeddedResource معرفی کنیم، نیاز است فایل csproj را به نحو زیر ویرایش کرد:

کدهای کامل این قسمت را از اینجا می‌توانید دریافت کنید: OpenAPISwaggerDoc-07.zip

dotnettips

شاید دیگر مطالب
روژانرا هم دوست داشته باشید

‫مستند سازی ASP.NET Core 2x API توسط OpenAPI Swagger – قسمت هفتم – سفارشی سازی ظاهر مستندات API

حتما بخوانید: سایر مطالب گروه آموزش

برای مشاهده فوری اخبار و مطالب در کانال تلگرام ما عضو شوید!



بیشترین بازدید یک ساعت گذشته


فیلم| رقص و آواز دختران در تلویزیون؛ صدا و سیما تابوشکنی کرد!