ดาวน์โหลด NSwag - ดาวน์โหลดซอร์สโค้ด NSwag

NSwag

หมวดหมู่อื่นๆ

v14.2.0 (.NET 9)

ดาวน์โหลด

NSWAG: เครื่องมือ Swagger/OpenAPI สำหรับ. NET, ASP.NET CORE และ TypeScript

NSWAG | NJSONSCHEMA | Apimundo | namotion.reflection

ประกาศ 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 Schema เพื่ออธิบายเว็บ API โครงการ NSWAG จัดเตรียมเครื่องมือในการสร้างข้อกำหนด OpenAPI จากตัวควบคุม ASP.NET Web API ที่มีอยู่และรหัสไคลเอนต์จากข้อกำหนด OpenAPI เหล่านี้

โครงการรวมฟังก์ชั่นของ SwashBuckle (OpenAPI/Swagger Generation) และ AutoRest (การสร้างไคลเอนต์) ในหนึ่งเครื่องมือ (ไม่จำเป็นต้องใช้ LIB ทั้งสองนี้) วิธีนี้สามารถหลีกเลี่ยงการเข้ากันได้มากมายและคุณสมบัติที่ไม่ได้อธิบายไว้อย่างดีโดยข้อกำหนดของ OpenAPI หรือ JSON Schema ได้รับการสนับสนุนที่ดีกว่า (เช่นการสืบทอด, enum และการจัดการอ้างอิง) โครงการ NSWAG ใช้ NJSonschema อย่างหนักสำหรับ. NET สำหรับการจัดการ JSON Schema และการสร้างคลาส/อินเตอร์เฟส C#/typeScript

ToolChainDiagram

โครงการได้รับการพัฒนาและดูแลโดย Rico Suter และผู้มีส่วนร่วมอื่น ๆ

คุณสมบัติ

สร้างข้อกำหนด Swagger 2.0 และ OpenAPI 3.0 จากตัวควบคุม C# ASP.NET (Core)
ให้บริการสเป็คผ่านมิดเดิลแวร์ ASP.NET (Core) โดยเลือกด้วย Swagger UI หรือ REDOC
สร้าง C# หรือไคลเอนต์ TypeScrip
ทุกอย่างสามารถเป็นไปโดยอัตโนมัติผ่าน CLI (แจกจ่ายผ่านเครื่องมือ NUGET หรือสร้างเป้าหมายหรือ NPM)
CLI กำหนดค่าผ่านไฟล์ JSON หรือ NSWAGSTUDIO Windows UI

วิธีการใช้ toolchain

ใช้งานง่าย Windows GUI, NSWAGSTUDIO
โดยใช้ openapi หรือ openapi ui owin และ asp.net core middlewares (ยังทำหน้าที่ Swagger UI) (แนะนำ)
ผ่านบรรทัดคำสั่ง (การรองรับ Windows, Mac และ Linux ผ่าน Mono หรือ. NET Core Console Binary, ผ่านแพ็คเกจ NPM)
ในรหัส C# ของคุณผ่าน NUGET
ในเป้าหมาย msbuild ของคุณ
ด้วยแท็ก ServiceProjectreference ใน. csproj (ดูตัวอย่าง) ของคุณ
ในฟังก์ชั่น Azure V2 ของคุณ (โครงการภายนอกอาจไม่ใช้เวอร์ชัน NSWAG ล่าสุด)

บทเรียน

เพิ่ม NSWAG ลงในแอป ASP.NET CORE ของคุณ
รวม NSWAG Toolchain เข้ากับโครงการ ASP.NET Web API ของคุณ
สร้างไคลเอนต์ TypeScript เชิงมุมจากแอสเซมบลีเว็บ API Web API ที่มีอยู่
การสอนวิดีโอ: วิธีการรวม NSWAG เข้ากับโครงการ ASP.NET Core Web API ของคุณ (5 นาที)

เครื่องกำเนิดไฟฟ้า openapi/swagger

ASP.NET WEB API ASSEMBLY ไปยัง OpenAPI (รองรับ. NET Core)
- aspnetcoreopenapidocumentGenerator
- WebapiopenapidocumentGenerator
  - สร้างข้อกำหนด OpenAPI สำหรับ Web API Controllers
- Webapitoopenapicommand
  - สร้างข้อกำหนด OpenAPI สำหรับคอนโทรลเลอร์ในชุดประกอบเว็บ API ภายนอก
  - ยังรองรับการโหลดของ. NET Core Assemblies
- typestoopenapicommand
  - สร้างข้อกำหนด OpenAPI ที่มีเฉพาะประเภทจาก. NET Assemblies

เครื่องกำเนิดรหัส

ไคลเอนต์ csharp
- csharpClientGenerator
  - สร้างไคลเอนต์ C# จากข้อกำหนด OpenAPI
  - สร้าง POCOS หรือคลาสที่ใช้ InotifyPropertyChanged สนับสนุน DTOS
  - ไคลเอนต์ที่สร้างขึ้นสามารถใช้กับ. NET, .NET Core, Xamarin และ. NET มาตรฐาน 1.4 โดยทั่วไป
CSHARP Controllers (การพัฒนา First/Schema First Development)
- csharpcontrollergenerator
  - สร้างตัวควบคุมเว็บ API ตามข้อกำหนดของ 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-Fetch-Client, Aurelia (ขึ้นอยู่กับเทมเพลต Fetch)
    - Axios (ดูตัวอย่าง)

การดาวน์โหลด

ดาวน์โหลด ตัวติดตั้ง NSWAGSTUDIO MSI ล่าสุด (NSWAGSTUDIO.MSI) (แอปพลิเคชันเดสก์ท็อป Windows)
ดาวน์โหลด เครื่องมือบรรทัดคำสั่ง 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 มาตรฐาน 1.3 / 2.0 และ. NET 4.5)
- ส่วนขยายเพื่ออ่านและเขียนข้อมูลจำเพาะของ Yaml OpenAPI
nswag.annotations (.NET มาตรฐาน 1.0 / 2.0 และ. NET 4.5)
- คุณลักษณะในการตกแต่งตัวควบคุมเว็บ API เพื่อควบคุมการสร้าง OpenAPI

Openapi Generation

nswag.generation (.NET มาตรฐาน 1.0 / 2.0 และ. NET 4.5)
- คลาสเพื่อสร้างข้อกำหนด OpenAPI
nswag.generation.webapi (.NET มาตรฐาน 1.0 / 2.0 และ. NET 4.5)
- คลาสที่จะสร้างข้อกำหนด OpenAPI จากตัวควบคุม Web API ดู WebapiopenapidocumentGenerator
nswag.generation.aspnetcore (.NET มาตรฐาน 1.6 / 2.0 และ. NET 4.5.1)
- (ทดลอง) คลาสเพื่อสร้างข้อกำหนด OpenAPI จากตัวควบคุม ASP.NET Core MVC โดยใช้ ApiexPlorer

การสร้างรหัส

NSWAG.CodeGeneration (.NET มาตรฐาน 1.3 / 2.0 / .NET 4.5.1)
- คลาสพื้นฐานเพื่อสร้างลูกค้าจากข้อกำหนดของ OpenAPI
nswag.codegeneration.csharp (.NET มาตรฐาน 1.3 และ. NET 4.5.1)
- คลาสที่จะสร้างไคลเอนต์ C# จากข้อกำหนดของ OpenAPI ดู CSHARPClientGenerator และ CSHARPControllerGenerator
nswag.codegeneration.typescript (.NET มาตรฐาน 1.3 และ. NET 4.5.1)
- คลาสที่จะสร้างไคลเอนต์ TypeScrip

ASP.NET และ ASP.NET CORE

nswag.aspnetcore (.NET มาตรฐาน 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 มาตรฐาน 1.6 / 2.0 และ. NET 4.5.1):
- คลาสเพื่อโหลดแอสเซมบลีใน appdomain ที่แยกได้และสร้างรายละเอียด OpenAPI จากตัวควบคุม Web API
NSWAG.COMMANDS (.NET มาตรฐาน 1.6 / 2.0 และ. NET 4.5.1+):
- คำสั่งสำหรับการใช้งานเครื่องมือบรรทัดคำสั่งและ UI
nswag.msbuild (msbuild .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 Package บนเป้าหมาย. NET CORE/UWP (ถ้า MSCORLIB หายไป)

เลเยอร์

การใช้งานใน C#

ในการลงทะเบียน Middlewares เพื่อสร้าง Spec OpenAPI และแสดง UI ให้ลงทะเบียน 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 ( ) ;

ตรวจสอบโครงการ Wiki สำหรับข้อมูลเพิ่มเติม

nswagstudio

เครื่องกำเนิดไฟฟ้าสามารถใช้ใน Windows GUI ที่สะดวกสบายและเรียบง่ายเรียกว่า nswagstudio:

ผู้สนับสนุนการสนับสนุนและการให้คำปรึกษา

บริษัท หรือบุคคลที่จ่ายเงินจำนวนมากสำหรับการดำเนินการแก้ไขปัญหาการสนับสนุนหรือการสนับสนุนแสดงอยู่ด้านล่าง ขอบคุณที่สนับสนุนโครงการนี้! คุณยังสามารถเป็นผู้สนับสนุนทางการเงิน: