NSwag

NSWAG: Die Prahlerei/OpenAPI -Toolchain für .NET, ASP.NET CORE und TISTICSCISCE

NSWAG | Njsonschema | Apimundo | Namotion.reflexion

Ankündigung von Apimundo: Ein API -Dokumentationssystem basierend auf NSWAG und NJSONSCHEMA?

NSWAG ist eine Prahlerei/OpenAPI 2.0 und 3.0 Toolchain für .NET, .NET CORE, Web -API, ASP.NET Core, TypeScript (JQuery, AngularJs, Angular 2+, Aurelia, Knockoutjs und mehr) und andere Plattformen, geschrieben in C#. Die OpenAPI/Swagger -Spezifikation verwendet das JSON- und JSON -Schema, um eine erholsame Web -API zu beschreiben. Das NSWAG -Projekt bietet Tools zum Generieren von OpenAPI -Spezifikationen von vorhandenen ASP.NET -Web -API -Controllern und Client -Code aus diesen OpenAPI -Spezifikationen.

Das Projekt kombiniert die Funktionalität von Swashbuckle (OpenAPI/Swagger -Generation) und Autorest (Client -Generation) in einem Toolchain (diese beiden Libs sind nicht erforderlich). Auf diese Weise können viele Inkompatibiliten vermieden werden, und Merkmale, die durch die OpenAPI -Spezifikation oder das JSON -Schema nicht gut beschrieben werden (z. B. Vererbung, Enum und Referenzhandhabung). Das NSWAG -Projekt verwendet NJsonschema für .NET für JSON -Schema und C#/TypeScript -Klasse/Schnittstellengenerierung stark.

Das Projekt wird von Rico Suter und anderen Mitwirkenden entwickelt und gepflegt.

Merkmale

• Generieren Sie die Spezifikationen von Swagger 2.0 und OpenAPI 3.0 aus C# ASP.NET (CORE) Controllern
• Servieren Sie die Spezifikationen über ASP.NET (CORE) Middleware, optional mit der SWAGVE UI oder RODOC
• Generieren Sie C# oder Typscript -Clients/Proxies aus diesen Spezifikationen
• Alles kann über CLI automatisiert werden (über Nuget -Tool oder Build -Ziel verteilt; oder NPM)
• CLI über JSON -Datei oder NSWAGSTUDIO Windows -Benutzeroberfläche konfiguriert

Möglichkeiten zur Verwendung der Toolchain

• Einfach zu verwenden Windows GUI, NSWAGSTUDIO
• Durch die Verwendung der OpenAPI- oder OpenAPI UI Owin und ASP.NET Core Middlewares (auch die Swagger UI (empfohlen) dient (empfohlen)
• Über Befehlszeile (Windows, Mac und Linux unterstützt über Mono oder .Net Core Console Binary, auch über NPM -Paket)
• In Ihrem C# Code über Nuget
• In Ihren MSBuild -Zielen
• Mit ServiceProjectrreenference -Tags in Ihrem .csproj (Vorschau)
• In Ihren Azure V2 -Funktionen (externes Projekt verwendet möglicherweise nicht die neueste NSWAG -Version)

Tutorials

• Fügen Sie NSWAG zu Ihrer ASP.NET -Core -App hinzu
• Integrieren Sie den NSWAG Toolchain in Ihr ASP.NET -Web -API -Projekt
• Generieren Sie einen Angular TypeScript -Client aus einer vorhandenen ASP.NET -Web -API -Web -Montage
• Video -Tutorial: So integrieren Sie NSWAG in Ihr ASP.NET -Web -API -Projekt (5 Minuten)

OpenAPI/Swagger -Generatoren

• ASP.NET -Web -API -Assembly an OpenAPI (unterstützt .NET Core)
  • ASPNETCOREOPENAPIDOCUMENTENGENERATOR
  • WebapiopenapidocumentGenerator
    • Generiert eine OpenAPI -Spezifikation für Web -API -Controller
  • Webapitoopenapicommand
    • Generiert eine OpenAPI -Spezifikation für Controller in einer externen Web -API -Montage
    • Unterstützt auch das Laden von .NET -Kernbaugruppen
  • SCHWEISSCHAFT
    • Generiert eine OpenAPI -Spezifikation, die nur Typen von .NET -Baugruppen enthält

Codegeneratoren

• CSHARP -Client
  • CSHARPCLIENTGENERATOR
    • Generiert C# Clients aus einer OpenAPI -Spezifikation
    • Generiert Pocos oder Klassen, die inotifyPropertychanged unterstützende DTOs implementieren
    • Die generierten Clients können mit vollem .NET, .NET Core, Xamarin und .NET Standard 1.4 im Allgemeinen verwendet werden
• CSHARP -Controller (Vertrag First/Schema First Development)
  • CSHARPCONTROLLENGENERATOR
    • Generiert Web -API -Controller basierend auf einer OpenAPI -Spezifikation (ASP.NET -Web -API und ASP.NET Core)
• TypeScript -Client
  • TypeScriptClientGenerator
    • Generiert TypeScript -Clients aus einer OpenAPI -Spezifikation
    • Verfügbare Vorlagen/unterstützte Bibliotheken:
      • JQuery mit Callbacks, JQueryCallbacks
      • JQuery mit Versprechen JQueryPromises
      • AngularJs mit $ http, AngularJS
      • Angular (v2+) mit dem HTTP -Dienst, Angular
      • Fenster.Fetch -API und ES6 -Versprechen, Fetch (Verwenden Sie diese Vorlage in Ihrer React/Redux -App)
      • Aurelia unter Verwendung des Httpclient von Aurelia-Fetch-Client, Aurelia (basierend auf der Fetch-Vorlage)
      • Axios (Vorschau)

Downloads

• Laden Sie die neueste NSWAGStudio MSI Installer (NSWAGSTUDIO.MSI) (Windows Desktop -Anwendung) herunter
• Laden Sie die neuesten NSWAG -Befehlszeilen -Tools und NSWAGSTUDIO (NSWAG.zip) herunter

NPM -Pakete

• NSWAG: Befehlszeilen -Tools (.NET und .NET Core) als NPM -Paket verteilt

Nuget -Pakete

Spezifikation

• Nswag.core
  • Die OpenAPI / Swagger -Leser- und Autor -Klassen siehe OpenAPIDOCUMENT (.NET Standard 1.0 / 2.0 und .NET 4.5)
• NSWAG.CORE.YAML (.NET Standard 1.3 / 2.0 und .NET 4.5)
  • Erweiterungen zum Lesen und Schreiben von YAML OpenAPI -Spezifikationen
• NSWAG.Annotations (.NET Standard 1.0 / 2.0 und .NET 4.5)
  • Attribute zur Dekoration von Web -API -Controllern zur Steuerung der OpenAPI -Generation

OpenAPI -Generation

• NSWAG.Generation (.NET Standard 1.0 / 2.0 und .NET 4.5)
  • Klassen zum Erstellen von OpenAPI -Spezifikationen
• Nswag.generation.webapi (.NET Standard 1.0 / 2.0 und .NET 4.5)
  • Klassen zum Generieren von OpenAPI -Spezifikationen von Web -API -Controllern finden Sie in WebapiopenapidocumentGenerator
• Nswag.generation.aspnetcore (.NET Standard 1.6 / 2.0 und .NET 4.5.1)
  • (Experimentelle) Klassen, um OpenAPI -Spezifikationen aus ASP.NET -Kern -MVC -Controllern mithilfe des Apiexplorers zu generieren

Codegenerierung

• NSWAG.CodeGeneration (.NET Standard 1.3 / 2.0 / .NET 4.5.1)
  • Grundklassen, um Clients aus OpenAPI -Spezifikationen zu generieren
• NSWAG.CodeGeneration.csharp (.NET Standard 1.3 und .NET 4.5.1)
  • Klassen zum Generieren von C# Clients aus OpenAPI -Spezifikationen finden Sie in CSHARPClientGenerator und CSHARPControllgenerator
• NSWAG.CodeGeneration.Typescript (.NET Standard 1.3 und .NET 4.5.1)
  • Klassen zum Generieren von Typscript -Clients aus OpenAPI -Spezifikationen finden Sie unter TypecriptClientGenerator

ASP.NET und ASP.NET CORE

• NSWAG.aspnetcore (.NET Standard 1.6 / 2.0 und .NET 4.5.1+)
• Nswag.aspnet.owin (.net 4.5+)
  • ASP.Net Core/Owin Middlewares zum Servieren von OpenAPI -Spezifikationen und der Prahlerei UI
• Nswag.aspnet.webapi (.net 4.5+)
  • ASP.NET -Web -API -Filter, der Ausnahmen serialisiert (jSonexceptionFilterAttribute)

Frontenden

• NSWAG.Assemblyloader (.NET Standard 1.6 / 2.0 und .NET 4.5.1):
  • Klassen zum Laden von Baugruppen in einer isolierten Appdomain und generieren OpenAPI -Spezifikationen von Web -API -Controllern
• NSWAG.Commands (.NET Standard 1.6 / 2.0 und .NET 4.5.1+):
  • Befehle für die Implementierungen des Befehlszeilen -Tools und die Benutzeroberfläche
• NSWAG.MSBUILD (MSBUILD .Targets):
  • Fügt Ihrem Visual Studio -Projekt eine .Targets -Datei hinzu, sodass Sie das NSWAG -Befehlszeilen -Tool in einem MSBuild -Ziel ausführen können, siehe MSBUILD
• NSWAG.ConSolecore (.NET Core 1.0, 1.1, 2.0, 2.1 und 2.2):
  • Befehlszeilen -Tool für .NET Core ( dotnet nswag )
  • <DotNetCliToolReference Include="NSwag.ConsoleCore" Version="..." />
• NSWAGSTUDIO (Schokolade, Fenster):
  • Paket zum Installieren der NSWAGSTUDIO- und Befehlszeilenwerkzeuge über schokoladig

CI -Nuget -Feed

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

Die Nuget -Pakete erfordern möglicherweise das Paket microsoft.netcore.portable.comPatibilität auf .NET Core/UWP -Zielen (wenn MSCORLIB fehlt).

Verwendung in C#

Um die Middlewares zu registrieren, um eine OpenAPI -Spezifikation zu generieren und die Benutzeroberfläche zu rendern, registrieren Sie NSWAG in 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
    }
}

Der folgende Code zeigt, wie Sie eine OpenAPI/Swagger -Spezifikation lesen und C# Client -Klassen generieren, um die beschriebenen Webdienste aufzurufen:

 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 ( ) ;

Weitere Informationen finden Sie im Projekt Wiki.

NSWAGSTUDIO

Die Generatoren können in einer komfortablen und einfachen Windows -GUI namens NSWAGSTUDIO verwendet werden:

Sponsoren, Unterstützung und Beratung

Unternehmen oder Personen, die einen erheblichen Betrag für die Umsetzung, Behebung von Problemen, Unterstützung oder Sponsoring gezahlt haben, sind unten aufgeführt. Vielen Dank, dass Sie dieses Projekt unterstützt haben! Sie können auch finanzieller Mitwirkender werden:

• Sponsor der Hauptbeiträge Rico Suter über Github
• Sponsorprojekt über Open Collective für NSWAG

Bitte wenden Sie sich an Rico Suter, um bezahlte Beratung und Unterstützung zu erhalten.

Mitwirkende

Dieses Projekt besteht dank aller Menschen, die einen Beitrag leisten. [Beitragen].

Sponsoren

Unterstützen Sie dieses Projekt, indem Sie Sponsor werden. Ihr Logo wird hier mit einem Link zu Ihrer Website angezeigt.

Top -Sponsoren:

Sponsoren:

Unterstützer

Vielen Dank an alle unsere Unterstützer!