وحید نصیری وحید نصیری
مطالب
مستند سازی ASP.NET Core 2x API توسط OpenAPI Swagger - قسمت هفتم - سفارشی سازی ظاهر مستندات API
امکان کنترل کامل و سفارشی سازی ظاهر نهایی Swagger-UI وجود دارد که جزئیات آن‌را در این قسمت بررسی خواهیم کرد.


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

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


برای بهبود این ظاهر می‌توان از Markdown استفاده کرد. بنابراین ابتدا تمام backslash‌های اضافه شده را که جهت نمایش خطوط جدید اضافه شده بودند، حذف می‌کنیم. در Markdown خطوط جدید با درج حداقل 2 فاصله (space) و یک سطر جدید مشخص می‌شوند. همچنین استفاده‌ی از ** سبب ضخیم شدن نمایش عبارت‌ها می‌شود. برای اینکه قطعه کد نوشته شده را در Markdown به صورت کدی با پس زمینه‌ای مشخص نمایش دهیم، پیش از شروع هر سطر آن نیاز است یک tab و یا 4 فاصله (space) درج شوند:
/// <remarks>
/// Sample request (this request updates the author's **first name**)
///
///     PATCH /authors/id
///     [
///         {
///           "op": "replace",
///           "path": "/firstname",
///           "value": "new first name"
///           }
///     ]
/// </remarks>
پس از این تغییرات خواهیم داشت:

که نسبت به حالت قبلی بسیار بهتر به نظر می‌رسد.
در نگارش فعلی، استفاده‌ی از 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، اینبار لیست قابلیت‌ها را به صورت باز شده نمایش نمی‌دهد:


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


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


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



اعمال تغییرات پیشرفته در 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 را به نحو زیر ویرایش کرد:
<Project Sdk="Microsoft.NET.Sdk.Web">
  <ItemGroup>
    <None Remove="EmbeddedAssets\index.html" />
  </ItemGroup>

  <ItemGroup>
    <EmbeddedResource Include="EmbeddedAssets\index.html" />
  </ItemGroup>
</Project>

کدهای کامل این قسمت را از اینجا می‌توانید دریافت کنید: OpenAPISwaggerDoc-07.zip
‫۵ سال و ۵ ماه قبل، دوشنبه ۲ اردیبهشت ۱۳۹۸، ساعت ۱۷:۰۵
وحید نصیری وحید نصیری
نظرات مطالب
بررسی روش ارتقاء به NET Core 1.1.
چند نکته در مورد VS 2015 و به روز رسانی‌های جدید NET Core.

آخرین نگارشی را که می‌توانید بدون مشکل با VS 2015 اجرا کنید، 1.0.0-preview2-1-003177 است (واقع در پوشه‌ی C:\Program Files\dotnet\sdk). پس از آن، این سیستم از نگارش JSON ایی فعلی به XML ایی تغییر کرده‌است و ابزارهای آن فقط برای VS 2017 ارائه شده‌اند و VS 2015 از این لحاظ دیگر هیچ پشتیبانی نخواهد داشت (حتی NuGet 4.0 هم برای آن به روز رسانی نشده‌است).

اگر برای مثال SDK مربوط به .NET Core 1.1.1. را نصب کنید و سپس فایل global.json را به 1.0.1 تغییر دهید:
 C:\Users\Vahid>dotnet --version
1.0.1
پروژه با خطای ذیل روبرو شده و در VS 2015 باز نخواهد شد. 
 The following error occurred attempting to run the project model server process (1.0.1).
Unable to start the process. No executable found matching command "dotnet-projectmodel-server"
بنابراین فایل global.json را که با VS 2017 منسوخ شده و حذف شده در نظر گرفته شده‌است، دیگر به روز رسانی نکنید.

اگر برای مثال SDK مربوط به .NET Core 1.1.1. را نصب کنید، درون VS 2015 قادر به Restore بسته‌های نیوگت نخواهید شد و با پیام خطای ذیل مواجه می‌شوید:
 \.vs\restore.dg(1,1): error MSB4025: The project file could not be loaded. Data at the root level is invalid. Line 1, position 1.
در این حالت از این پس سه راه را پیش رو خواهید داشت:
1- ارتقاء به VS 2017 و فراموش کردن VS 2015
2- استفاده از VS 2015 و بازیابی بسته‌ها از طریق خط فرمان (چون دیگر ابزارهای VS 2015 با نگارش جدید SDK سازگار نیستند)
 برای این منظور دقت کنید در پنجره‌ی output ویژوال استودیوی 2015، چه فرمانی صادر شده‌است که سبب بروز خطای فوق گردیده‌است:
 "C:\Program Files\dotnet\dotnet.exe" restore "D:\project1\.vs\restore.dg"
از طریق خط فرمان به پوشه‌‌های پروژه‌ها وارد شده (دکمه‌ی shift را نگه داشته و کلیک راست کنید. سپس گزینه‌ی open command window here را انتخاب نمائید) و دستور فوق را اجرا کنید. این دستور از این پس تنها در خط فرمان بدون مشکل اجرا می‌شود و نه در داخل VS 2015.
پس از آن پروژه بدون مشکل Build می‌شود (در داخل VS 2015).
3- و یا ... این SDK جدید 1.0.1 را حذف کنید از سیستم (اگر می‌خواهید با VS 2015 بدون دردسر کار کنید).


و یا کلا به VSCode مهاجرت کنید و VS کامل را فراموش کنید. VSCode با ابزارهای خط فرمان NET Core. کار می‌کند و در این حالت به سادگی می‌توان همواره آخرین نگارش NET Core. را مورد استفاده قرار داد؛ بدون نگرانی از سازگاری ابزارهای ویژوال استودیو با آن. چون اساسا هیچ نوع وابستگی به این ابزارها ندارد. همچنین حجم بسیار کمتری هم داشته و اگر با دریافت VS 2017 مشکل دارید، مهاجرت به VSCode انتخاب بسیار مناسبی است.


خلاصه‌ی بحث
از این پس برای کار کردن بدون دردسر با نگارش‌های جدید NET Core. تنها دو راه را پیش رو دارید: مهاجرت به VS 2017 و یا مهاجرت به VSCode.
‫۷ سال و ۷ ماه قبل، شنبه ۲۱ اسفند ۱۳۹۵، ساعت ۱۶:۳۳
امیر قراجه داغی امیر قراجه داغی
نظرات اشتراک‌ها
Visual Studio 2015 Update 3 منتشر شد
با سلام !
 هنگام آپدیت سوم ویژوال استودیو 2015 سیستم به اینترنت متصل نبود و بعد از کامل شدن نصب آپدیت سوم ، هشدار‌های زیر را به نمایش گذاشت ، آفلاین فایل‌ها رو از کجا دانلود کنیم ؟  چه راه حلی برای نصب این فایل‌ها پیشنهاد می‌دهید ؟

‫۸ سال و ۳ ماه قبل، سه‌شنبه ۲۹ تیر ۱۳۹۵، ساعت ۲۰:۱۶