NSwag

NSWAG: مجموعة أدوات Swagger/OpenAPI لـ .NET و ASP.NET Core و TypeScript

nswag | NJSonschema | Apimundo | namotion.relection

الإعلان عن Apimundo: نظام وثائق API يعتمد على NSWAG و NJSONSCHEMA؟

NSWAG عبارة عن مجموعة أدوات Swagger/OpenAPI 2.0 و 3.0 لـ .NET و .NET Core و Web API و ASP.NET Core و TypeScript (jQuery و AngularJs و Angular 2+ و Aurelia و KnockoutJs والمزيد) وغيرها من المنصات ، مكتوبة في C#. تستخدم مواصفات OpenAPI/Swagger مخطط JSON و JSON لوصف واجهة برمجة تطبيقات الويب المريحة. يوفر مشروع NSWAG أدوات لإنشاء مواصفات OpenAPI من وحدات التحكم API ASP.NET الحالية ورمز العميل من مواصفات OpenAPI هذه.

يجمع المشروع بين وظائف swashbuckle (جيل OpenAPI/Swagger) و Autorest (توليد العميل) في واحدة أدوات (ليست هناك حاجة إلى هاتين libs). وبهذه الطريقة ، يمكن تجنب الكثير من عدم التوافق والميزات التي لا يتم وصفها جيدًا بواسطة مواصفات OpenAPI أو مخطط JSON بشكل أفضل (مثل الميراث ، التعداد والتعامل المرجعي). يستخدم مشروع NSWAG بشكل كبير NJSonsChema لـ .NET للتعامل مع مخطط JSON وتوليد فئة/واجهة C#/TypeScript.

تم تطوير المشروع وصيانته بواسطة Rico Suter وغيرهم من المساهمين.

سمات

• قم بإنشاء Swagger 2.0 و OpenAPI 3.0 مواصفات من C# ASP.NET (CORE)
• خدمة المواصفات عبر الوسيطة ASP.NET (CORE) ، اختياريًا باستخدام واجهة مستخدم Swagger أو Redoc
• قم بإنشاء عملاء C# أو TypeScript من هذه المواصفات
• يمكن تلقائي كل شيء عبر CLI (موزعة عبر أداة nuget أو هدف البناء ؛ أو NPM)
• تم تكوين CLI عبر ملف JSON أو Nswagstudio Windows UI

طرق لاستخدام مجموعة الأدوات

• سهل الاستخدام Windows GUI ، nswagstudio
• باستخدام Openapi أو Openapi UI Owin و ASP.NET Core Middleares (يخدم أيضًا واجهة المستخدم Swagger) (موصى بها)
• عبر سطر الأوامر (دعم Windows و Mac و Linux من خلال Mono أو .NET Core Console Binary ، وأيضًا عبر حزمة NPM)
• في رمز C# الخاص بك ، عبر Nuget
• في أهداف MSBuild الخاصة بك
• مع علامات ServiceProjectReference في .csproj (معاينة)
• في وظائف Azure V2 الخاصة بك (المشروع الخارجي ، قد لا تستخدم أحدث إصدار من NSWAG)

دروس

• أضف nswag إلى تطبيق ASP.NET Core الخاص بك
• دمج مجموعة أدوات NSWAG في مشروع ASP.NET Web API
• قم بإنشاء عميل TyperScript الزاوي من مجموعة ويب ASP.NET Web API موجودة
• برنامج الفيديو التعليمي: كيفية دمج NSWAG في مشروع ASP.NET Core Web API (5 دقائق)

مولدات Openapi/Swagger

• ASP.NET Web API Assembly to OpenAPI (يدعم .NET Core)
  • ASPNETCOREOPENPENAPIDOCINETGERATOR
  • webapiopenapidocumentgenerator
    • يولد مواصفات OpenAPI لوحدات التحكم في واجهة برمجة تطبيقات الويب
  • WebApitoOpenApicommand
    • يولد مواصفات OpenAPI لوحدات التحكم في مجموعة ويب ويب خارجية
    • يدعم أيضًا تحميل مجموعات .NET Core
  • typestoopenapicommand
    • يولد مواصفات OpenAPI تحتوي فقط

مولدات الكود

• عميل CSHARP
  • csharpclientgenerator
    • يولد عملاء C# من مواصفات OpenAPI
    • يولد POCOS أو فئات تنفذ InotifyPropertyChanged دعم DTOs
    • يمكن استخدام العملاء الذين تم إنشاؤهم باستخدام CORE ،
• وحدات تحكم CSHARP (العقد الأول/تطوير المخطط الأول)
  • CsharpControllerGenerator
    • يقوم بإنشاء وحدات التحكم في واجهة برمجة تطبيقات الويب بناءً على مواصفات OpenAPI (ASP.NET Web API و ASP.NET CORE)
• عميل TypeScript
  • TypeScriptClientGenerator
    • يولد عملاء TypeScript من مواصفات OpenAPI
    • القوالب المتاحة/المكتبات المدعومة:
      • jQuery مع عمليات الاسترجاعات ، JQueryCallbacks
      • jQuery مع الوعود JQueryPromises
      • AngularJs باستخدام $ HTTP ، AngularJS
      • Angular (V2+) باستخدام خدمة HTTP ، Angular
      • Window.Fetch API و ES6 وعود ، Fetch (استخدم هذا القالب في تطبيق React/Redux)
      • Aurelia باستخدام httpclient من Aurelia-Betch-Client ، Aurelia (استنادًا إلى قالب الجلب)
      • Axios (معاينة)

التنزيلات

• قم بتنزيل أحدث تثبيت Nswagstudio MSI (Nswagstudio.msi) (تطبيق Windows Desktop)
• قم بتنزيل أحدث أدوات سطر أوامر NSWAG و Nswagstudio (nswag.zip)

حزم NPM

• NSWAG: توزيع أدوات سطر الأوامر (.NET و .NET CORE) كحزمة NPM

حزم nuget

مواصفة

• nswag.core
  • فصول قارئ وكاتب Openapi / Swagger ، انظر OpenApidocument (.NET Standard 1.0 / 2.0 و .NET 4.5)
• nswag.core.yaml (.NET Standard 1.3 / 2.0 و .net 4.5)
  • امتدادات لقراءة وكتابة مواصفات yaml openapi
• nswag.annotations (.NET Standard 1.0 / 2.0 و .NET 4.5)
  • يعتمد على تزيين وحدات التحكم في واجهة برمجة التطبيقات للسيطرة على جيل OpenAPI

جيل Openapi

• nswag.generation (.NET Standard 1.0 / 2.0 و .NET 4.5)
  • دروس لإنشاء مواصفات OpenAPI
• nswag.generation.webapi (.NET Standard 1.0 / 2.0 و .NET 4.5)
  • فصول لإنشاء مواصفات OpenAPI من وحدات التحكم في واجهة برمجة تطبيقات الويب ، راجع WebApiopenapidocumentGenerator
• nswag.generation.aspnetcore (.NET Standard 1.6 / 2.0 و .net 4.5.1)
  • (تجريبي) فئات لإنشاء مواصفات OpenAPI من وحدات التحكم MVC ASP.NET Core باستخدام Apiexplorer

توليد الكود

• nswag.codegeneration (.NET Standard 1.3 / 2.0 / .NET 4.5.1)
  • الفصول الأساسية لإنشاء عملاء من مواصفات OpenAPI
• nswag.codegeneration.csharp (.NET Standard 1.3 و .net 4.5.1)
  • فصول لإنشاء عملاء C# من مواصفات OpenAPI ، راجع CsharpClientGenerator و CsharpControllerGenerator
• nswag.codegeneration.typescript (.NET Standard 1.3 و .net 4.5.1)
  • فصول لإنشاء عملاء TypeScript من مواصفات OpenAPI ، انظر TypeScriptClientGenerator

ASP.NET و ASP.NET CORE

• nswag.aspnetcore (.NET Standard 1.6 / 2.0 و .NET 4.5.1+)
• nswag.aspnet.owin (.net 4.5+)
  • ASP.NET CORE/OWIN Middlewares لخدمة مواصفات OpenAPI و Swagger UI
• nswag.aspnet.webapi (.net 4.5+)
  • مرشح ASP.NET Web API الذي يقوم بتسلسل الاستثناءات (JSOnexceptionFilterattribute)

الجبهة

• Nswag.assemblyloader (.NET Standard 1.6 / 2.0 و .NET 4.5.1):
  • فصول لتحميل التجميعات في AppDomain معزولة وإنشاء مواصفات OpenAPI من وحدات التحكم في واجهة برمجة التطبيقات ويب
• nswag.commands (.NET Standard 1.6 / 2.0 و .NET 4.5.1+):
  • أوامر لتطبيقات أداة سطر الأوامر وواجهة المستخدم
• nswag.msbuild (msbuild .targets):
  • يضيف ملف .targets إلى مشروع Visual Studio الخاص بك ، بحيث يمكنك تشغيل أداة سطر الأوامر NSWAG في هدف MSBuild ، انظر MSBuild
• nswag.consolecore (.NET Core 1.0 ، 1.1 ، 2.0 ، 2.1 و 2.2):
  • أداة سطر الأوامر لـ .NET Core ( dotnet nswag )
  • <DotNetCliToolReference Include="NSwag.ConsoleCore" Version="..." />
• Nswagstudio (الشوكولاتة ، Windows):
  • حزمة لتثبيت Nswagstudio وأدوات سطر الأوامر عبر الشوكولاتة

CI NUGET تغذية

https://www.myget.org/f/nswag/api/v3/index.json

قد تتطلب حزم nuget حزمة microsoft.netcore.portable.compatibility على أهداف .NET Core/UWP (إذا كان Mscorlib مفقودًا).

الاستخدام في ج#

لتسجيل الأدوات الوسطى لإنشاء مواصفات OpenAPI وتقديم واجهة المستخدم ، قم بتسجيل nswag في Startup.cs :

 public class Startup
{
    .. .

    public void ConfigureServices ( IServiceCollection services )
    {
        services . AddOpenApiDocument ( ) ; // add OpenAPI v3 document
//      services.AddSwaggerDocument(); // add Swagger v2 document
    }

    public void Configure ( IApplicationBuilder app , IHostingEnvironment env , ILoggerFactory loggerFactory )
    {
        .. .

        app . UseOpenApi ( ) ; // serve OpenAPI/Swagger documents
        app . UseSwaggerUi ( ) ; // serve Swagger UI
        app . UseReDoc ( ) ; // serve ReDoc UI
    }
}

يوضح الرمز التالي كيفية قراءة مواصفات OpenAPI/Swagger وإنشاء فئات العميل C# للاتصال بخدمات الويب الموصوفة:

 var document = await OpenApiDocument . FromFileAsync ( "openapi.json" ) ;
var clientSettings = new CSharpClientGeneratorSettings 
{
    ClassName = "MyClass" ,
    CSharpGeneratorSettings = 
    {
        Namespace = "MyNamespace"
    }
} ;

var clientGenerator = new CSharpClientGenerator ( document , clientSettings ) ;
var code = clientGenerator . GenerateFile ( ) ;

تحقق من مشروع ويكي لمزيد من المعلومات.

nswagstudio

يمكن استخدام المولدات في واجهة مستهجمة Windows مريحة وبسيطة تسمى Nswagstudio:

الرعاة والدعم والاستشارات

فيما يلي الشركات أو الأفراد الذين دفعوا مبلغًا كبيرًا لتنفيذ أو إصلاح المشكلات أو الدعم أو الرعاية. شكرا لدعم هذا المشروع! يمكنك أيضًا أن تصبح مساهمًا ماليًا:

• راعي المساهم الرئيسي ريكو سوتر عبر جيثب
• مشروع الراعي عبر Open Collective لـ NSWAG

يرجى الاتصال بـ Rico Suter للاستشارات والدعم المدفوع.

المساهمين

هذا المشروع موجود بفضل جميع الأشخاص الذين يساهمون. [يساهم].

الرعاة

دعم هذا المشروع من خلال أن يصبح راعياً. سيظهر شعارك هنا مع رابط لموقع الويب الخاص بك.

الرعاة الأعلى:

الرعاة:

مؤيدون

شكرا لجميع مؤيدينا!