Startseite>Programmierbezogen>Anderer Quellcode
Herunterladen
Wichtige Bescheid, wenn Sie zwischen den wichtigsten Versionen aktualisieren!
* Wenn Sie von 4.x auf 5.x aktualisieren, müssen sich mehrere Änderungen bewusst sein. Weitere Informationen finden Sie in den Versionshinweise
* Wenn Sie den Sprung von 3.x zu 4.x machen, gibt es dort auch Drachen. Sehen Sie hier diese Release -Notizen an

Swashbuckle.aspnetcore

Swagger Tooling für APIs, die mit ASP.NET CORE erstellt wurden. Generieren Sie eine schöne API -Dokumentation, einschließlich einer Benutzeroberfläche, um Operationen direkt von Ihren Routen, Controllern und Modellen zu untersuchen und zu testen.

Zusätzlich zu seinem Generator von Prahlerei 2.0 und OpenAPI 3.0 bietet Swashbuckle auch eine eingebettete Version des fantastischen Swagger-UI, das von der erzeugten Prahlerei JSON angetrieben wird. Dies bedeutet, dass Sie Ihre API durch lebende Dokumentation ergänzen können, die immer mit dem neuesten Code synchronisiert ist. Das Beste ist, dass es nur eine minimale Codierung und Wartung erfordert, sodass Sie sich auf den Aufbau einer fantastischen API konzentrieren können.

Und das ist nicht alles ...

Sobald Sie eine API haben, die sich in der Prahlerei beschreiben kann, haben Sie die Schatzkiste von Swagger-basierten Tools geöffnet, einschließlich eines Client-Generators, der auf eine breite Palette beliebter Plattformen gerichtet werden kann. Weitere Informationen finden Sie in Swagger-Codegen.

Kompatibilität

Swashbuckle -Version ASP.NET CORE Swagger / OpenAPI Spec. Swagger-ui Redoc ui
CI > = 2.0.0 2.0, 3.0 5.xx 2.xx
6.9.0 > = 2.0.0 2.0, 3.0 5.17.14 2.1.5
5.6.3 > = 2.0.0 2.0, 3.0 3.32.5 2.0.0-rc.40
4.0.0 > = 2.0.0, <3.0.0 2.0 3.19.5 1.22.2
3.0.0 > = 1.0.4, <3.0.0 2.0 3.17.1 1.20.0
2.5.0 > = 1.0.4, <3.0.0 2.0 3.16.0 1.20.0

Erste Schritte

  1. Installieren Sie das Standard -Nuget -Paket in Ihrer ASP.NET -Kernanwendung. 

    Package Manager : Install-Package Swashbuckle.AspNetCore
CLI : dotnet add package Swashbuckle.AspNetCore

  2. Registrieren Sie im Swagger -Generator in der Methode ConfigureServices von Startup.cs und definieren Sie eine oder mehrere Prahlerin -Dokumente.

     unter Verwendung von Microsoft.openapi.models;
     Services.Addmvc (); Services.addswaggergen (c => {C.Swaggerdoc ("v1", neue OpenAPIInfo {title = "my api", Version = "v1"});});

  3. Stellen Sie sicher, dass Ihre API -Aktionen und -Parameter mit explizitem "HTTP" und "aus" Bindungen dekoriert sind.

     [HTTPPOST] Public void CreateProduct ([From Body] Produktprodukt) ...
     [Httpget] public iEnumerable <produkt> SearchProducts ([FromQuery] String -Schlüsselwörter) ...

    Hinweis: Wenn Sie die explizite Parameterbindungen weglassen, beschreibt der Generator sie standardmäßig als "Abfrage" -Paramien.

  4. In der Configure sollten Sie die generierte Prahlerei als JSON -Endpunkt (en) durch eine der folgenden Methoden freilegen:

     app.Mapendpoints (Endpoints => {// ... Endpoints.mapswagger ();});
     app.useswagger ();

    Zu diesem Zeitpunkt können Sie Ihre Anwendung verbessern und den generierten Prahler -JSON unter "/Swagger/v1/swagger.json" anzeigen.

    • Middleware einfügen

    • Fügen Sie Endpunkte hinzu, wenn Sie das Endpoint-basierte Routing verwenden.

  5. Fügen Sie optional die Swagger-UI-Middleware ein, wenn Sie interaktive Dokumentation freilegen möchten, und geben Sie den Swagger JSON-Endpunkt (en) an, um sie aus zu versorgen.

     app.useswaggerui (c => {c.swaggerendpoint ("v1/Swagger.json", "meine API v1");});

    Jetzt können Sie Ihre Bewerbung neu starten und die automatisch generierten, interaktiven Dokumente unter "/Swagger" überprüfen.

System.text.json (STJ) gegen Newtonsoft

In Versionen vor 5.0.0 wird Swashbuckle Schema (Beschreibungen der von einer API entlarvten Datentypen) basierend auf dem Verhalten des Newtonsoft Serializer generieren. Dies machte Sinn, weil das der Serializer war, der zu dieser Zeit mit ASP.NET Core versandt wurde. Seit Version 3.0.0 führt ASP.NET Core jedoch ein neues Serializer -System ein. tapt-in. Von Smashbuckle 5.0.0 und über ein ähnliches Muster hinaus wird verwendet. Das heißt, außerhalb des Box Swashbuckle wird davon ausgehen, dass Sie den STJ- Serializer verwenden und Schema basierend auf seinem Verhalten generieren. Wenn Sie Newtonsoft verwenden, müssen Sie ein separates Swashbuckle-Paket installieren und sich explizit abmelden. Dies ist ein erforderlicher Schritt, unabhängig davon, welche Version von ASP.Net Core Sie verwenden .

Zusammenfassend ...

Wenn Sie System.Text.json (STJ) verwenden, ist das oben beschriebene Setup ausreichend und STJ -Optionen/-attribute werden vom Swagger -Generator automatisch geehrt.

Wenn Sie Newtonsoft verwenden, müssen Sie ein separates Paket installieren und explizit entscheiden, um sicherzustellen, dass die Newtonsoft -Einstellungen/-attribute vom Swagger-Generator automatisch geehrt werden: 

Package Manager : Install-Package Swashbuckle.AspNetCore.Newtonsoft
CLI : dotnet add package Swashbuckle.AspNetCore.Newtonsoft
 Services.Addmvc (); Services.addswaggergen (c => {C.Swaggerdoc ("v1", neue OpenAPIInfo {title = "my api", Version = "v1"});}); Dienste.AddswaggergenNewtonsoftSupport (); // Explizite Opt -In - muss nach Addswaggergen () platziert werden

Swashbuckle, Apiexplorer und Routing

Swashbuckle verlässt sich stark auf ApiExplorer , die API -Metadatenschicht, die mit ASP.NET -Kern versendet wird. Wenn Sie den AddMvc -Helfer verwenden, um den MVC -Stack zu starten, wird Apiexplorer automatisch registriert und SB funktioniert ohne Probleme. Wenn Sie AddMvcCore für einen gepaarten MVC-Stack verwenden, müssen Sie den Apiexplorer-Dienst explizit hinzufügen:

 Services.Addmvccore (). Addapiexplorer ();

Wenn Sie konventionelle Routing (im Gegensatz zu Attributrouting) verwenden, werden alle Controller und Aktionen auf denjenigen Controller, die konventionelles Routing verwenden, nicht in Apiexplorer dargestellt, was bedeutet Operationen von ihnen. Zum Beispiel:

 app.usemvc (Routes => {// Swaggergen findet keine Controller, die über diese Technik weitergeleitet werden. Routes.mapRoute ("Standard", "{Controller = Home}/{action = index}/{id?}") ;});

Sie müssen Attribut -Routing für alle Controller verwenden, die Sie in Ihren Prahlerdokumenten (n) darstellen möchten:

 [Route ("Beispiel")] public class examplecontroller: Controller {[httpget ("")] public iActionResult dostuff () { / ** /}}

Weitere Informationen finden Sie in der Routing -Dokumentation.

Komponenten

Swashbuckle besteht aus mehreren Komponenten, die je nach Ihren Anforderungen zusammen oder einzeln verwendet werden können. Im Kern gibt es einen Swagger-Generator, Middleware, um ihn als JSON-Endpunkte und eine verpackte Version des Swagger-UI aufzudecken. Diese 3 Pakete können mit dem "metapackage" von Swashbuckle.AspNetCore installiert werden. Sie werden nahtlos zusammenarbeiten (siehe Start), um wunderschöne API -Dokumente bereitzustellen, die automatisch aus Ihrem Code generiert werden.

Darüber hinaus gibt es Add-On-Pakete (CLI-Tools, eine alternative Benutzeroberfläche usw.), die Sie bei Bedarf optional installieren und konfigurieren können.

"Core" -Pakete (dh über swashbuckle.aspnetcore installiert)

Paket Beschreibung
Swashbuckle.aspnetcore.swagger Entellt Swagger JSON -Endpunkte. Es wird erwartet, dass eine Implementierung von ISwaggerProvider im DI -Container registriert wird, den es zum Abrufen von OpenAPIDocument(s) , die dann als serialisiertes JSON entlarvt werden
Swashbuckle.aspnetcore.swaggergen Injiziert eine Implementierung von ISwaggerProvider , die von der obigen Komponente verwendet werden kann. Diese spezielle Implementierung generiert OpenApiDocument(s) aus Ihren Routen, Controllern und Modellen
Swashbuckle.aspnetcore.swaggerui Entellt eine eingebettete Version der Swagger-UI. Sie geben die API -Endpunkte an, an denen sie Prahlerei JSON erhalten können, und verwendet sie, um interaktive Dokumente für Ihre API zu betreiben

Zusätzliche Pakete

Paket Beschreibung
Swashbuckle.aspnetcore.Annotations Enthält eine Reihe von benutzerdefinierten Attributen, die auf Controller, Aktionen und Modelle angewendet werden können, um die generierte Prahlerei zu bereichern
Swashbuckle.aspnetcore.cli Bietet eine Befehlszeilenschnittstelle zum Abrufen von Prahlerei direkt von einer Startmontage und zum Schreiben in Datei
Swashbuckle.aspnetcore.redoc Entellt eine eingebettete Version der Redoc-Benutzeroberfläche (eine Alternative zu Swagger-UI) frei

Community -Pakete

Diese Pakete werden von der Open-Source-Community bereitgestellt.

Paket Beschreibung
Swashbuckle.aspnetcore.filters Einige nützliche Swashbuckle -Filter, die zusätzliche Dokumentation, z.
Unchase.swashbuckle.aspnetcore.extensions Einige nützliche Erweiterungen (Filter), die zusätzliche Dokumentationen hinzufügen, z.
Microelements.swashbuckle.fluentvalidation Verwenden Sie die Regeln der fließenden Validation anstelle von Komponentmodel -Attributen, um die erzeugten Prahlereischemata zu erhöhen
Mmlib.swaggerforocelot Aggregate Dokumentationen über Microservices direkt auf Ocelot API Gateway

Konfiguration und Anpassung

Die oben beschriebenen Schritte bringen Sie mit minimalem Setup zum Betrieb. Swashbuckle bietet jedoch viel Flexibilität, um sich nach Belieben anzupassen. In der folgenden Tabelle finden Sie die vollständige Liste der Optionen:

  • Swashbuckle.aspnetcore.swagger

    • Ändern Sie den Pfad für Prahlerei -JSON -Endpunkte

    • Ändern Sie die Prahlerei mit Anforderungskontext

    • Serialisieren Sie Prahlerin JSON im 2.0 -Format

    • Arbeiten mit virtuellen Verzeichnissen und umgekehrten Proxys

    • Anpassen, wie das OpenAPI -Dokument serialisiert wird

  • Swashbuckle.aspnetcore.swaggergen

    • Zuweisen explizite OperationIDs

    • Listen Sie Operationsantworten auf

    • FLAGS erforderliche Parameter und Schemaeigenschaften

    • Behandeln Sie Formulare und Datei -Uploads

    • Datei -Downloads verarbeiten

    • Beschreibungen aus XML -Kommentaren eingeben

    • Stellen Sie globale API -Metadaten zur Verfügung

    • Generieren Sie mehrere Prahlerin -Dokumente

    • Veraltete Operationen und/oder Schema -Eigenschaften auslassen

    • Willkürliche Operationen weglassen

    • Anpassen von Betriebs -Tags (z. B. für die UI -Gruppierung)

    • Operation Sortierreihenfolge ändern (z. B. für die UI -Sortierung)

    • Passen Sie Schema -IDs an

    • Schema für bestimmte Typen überschreiben

    • Generator mit Betriebs-, Schema- und Dokumentfiltern erweitern

    • Fügen Sie Sicherheitsdefinitionen und Anforderungen hinzu

    • Fügen Sie Sicherheitsdefinitionen und Anforderungen für Trägerauth hinzu

    • Vererbung und Polymorphismus

  • Swashbuckle.aspnetcore.swaggerui

    • Änderung des relativen Weges zur Benutzeroberfläche

    • Dokumenttitel ändern

    • Ändern Sie CSS- oder JS -Pfade

    • Listen Sie mehrere Prahlerin -Dokumente auf

    • Wenden Sie Swagger-UI-Parameter an

    • Benutzerdefinierte JavaScript injizieren

    • CSS injizieren

    • Passen Sie index.html an

    • Aktivieren Sie OAuth2.0 Flows

    • Verwenden

  • Swashbuckle.aspnetcore.Annotations

    • Anmerkungen installieren und aktivieren

    • AnArich Operation Metadata

    • Anreicherung der Reaktionsmetadaten

    • Anreicherung der Parametermetadaten

    • Enrich RequestBody Metadata

    • Anreicherungsschema -Metadaten

    • Wenden Sie Schemafilter auf bestimmte Typen an

    • Fügen Sie Tag -Metadaten hinzu

  • Swashbuckle.aspnetcore.cli

    • Rufen Sie Prahlerei direkt von einer Startversammlung ab

    • Verwenden Sie das CLI -Tool mit einer benutzerdefinierten Host -Konfiguration

  • Swashbuckle.aspnetcore.redoc

    • Änderung des relativen Weges zur Benutzeroberfläche

    • Dokumenttitel ändern

    • Anwenden Sie Redoc -Parameter an

    • CSS injizieren

    • Passen Sie index.html an

Swashbuckle.aspnetcore.swagger

Ändern Sie den Pfad für Prahlerei -JSON -Endpunkte

Standardmäßig wird Swagger JSON auf der folgenden Route entlarvt - "/Swagger/ <DocumentName >/swagger.json". Bei Bedarf können Sie dies ändern, wenn Sie die Swagger Middleware aktivieren. Benutzerdefinierte Routen müssen den Parameter {documentName} enthalten.

 app.useswagger (c => {c.RoutTemplate = "api-docs/{documentName} /Swagger.json";})

Hinweis: Wenn Sie die Swaggerui Middleware verwenden, müssen Sie auch die Konfiguration aktualisieren, um die neuen Endpunkte widerzuspiegeln:

 app.useswaggerui (c => {c.swaggerendpoint ("/api-docs/v1/swagger.json", "my api v1");})

Hinweis: Wenn Sie auch den relativen Pfad, auf dem die Benutzeroberfläche selbst verfügbar ist, aktualisieren müssen, müssen Sie den Anweisungen im Veränderung des relativen Pfades zur Benutzeroberfläche befolgen.

Ändern Sie die Prahlerei mit Anforderungskontext

Wenn Sie einige Swagger -Metadaten basierend auf der aktuellen Anforderung festlegen müssen, können Sie einen Filter konfigurieren, der vor der Serialisierung des Dokuments ausgeführt wird.

 app.USSeSwagger (c => {C. preserializeFilters.add ((Swagger, httpreq) => {Swagger.Servers = New List <S OpenAPIERVERVERVERVERVERVERVERVERVERVERVERVERVERVERVERVERVERVERVERVERVERVERVERVERVERVERVERVERVERVERVERS. Host.Value} "}};});});

Das OpenApiDocument und das aktuelle HttpRequest werden beide an den Filter übergeben. Dies bietet viel Flexibilität. Sie können beispielsweise einen expliziten API -Server auf der Grundlage des "Host" -Headers (wie gezeigt) hinzufügen oder Sitzungsinformationen oder einen Autorisierungsheader inspizieren und Vorgänge aus dem Dokument basierend auf den Benutzerberechtigungen entfernen.

Serialisieren Sie die Prahlerei im 2.0 -Format

Standardmäßig generiert und enthüllt Swashbuckle Swagger JSON in Version 3.0 der Spezifikation, die offiziell als OpenAPI -Spezifikation bezeichnet wird. Um die Kompatibilität rückwärts zu unterstützen, können Sie sie jedoch mit der folgenden Option im Format 2.0 weiterhin aussetzen:

 app.useswagger (c => {c.Serializeasv2 = true;});

Arbeiten mit virtuellen Verzeichnissen und umgekehrten Proxys

Virtuelle Verzeichnisse und umgekehrte Proxys können Probleme für Anwendungen verursachen, die Links und Weiterleitungen generieren, insbesondere wenn die App absolute URLs basierend auf dem Host -Header und anderen Informationen aus der aktuellen Anfrage zurückgibt. Um diese Probleme zu vermeiden, verwendet Swashbuckle nach Möglichkeit relative URLs und fördert ihre Verwendung bei der Konfiguration der Swaggerui und der Redoc Middleware.

Um beispielsweise die Swaggerui Middleware zu verkabeln, stellen Sie die URL einen oder mehrere OpenAPI/Swagger -Dokumente zur Verfügung. Dies ist die URL, die die Swagger-UI, eine clientseitige Anwendung, anruft, um Ihre API-Metadaten abzurufen. Um sicherzustellen, dass dies hinter virtuellen Verzeichnissen und umgekehrten Proxys funktioniert, sollten Sie dies relativ zum RoutePrefix der Swagger-UI selbst ausdrücken:

 app.useswaggerui (c => {C.Routeprefix = "Swagger";

Hinweis: In früheren Versionen der Dokumente haben Sie dies möglicherweise als root-relativen Link ( /swagger/v1/swagger.json ) gesehen. Dies funktioniert nicht, wenn Ihre App in einem virtuellen IIS -Verzeichnis oder hinter einem Stellvertreter gehostet wird, der den Anforderungsweg vor dem Weiterleiten abschneidet. Wenn Sie zur oben gezeigten Seitensyntax wechseln, sollte sie in allen Fällen funktionieren.

Anpassen, wie das OpenAPI -Dokument serialisiert wird

Standardmäßig wird Swashbuckle das OpenAPI -Dokument mithilfe der Serialize -Methoden im OpenAPI -Dokumentobjekt serialisieren. Wenn eine individuelle Serialisierung erwünscht ist, ist es möglich, einen benutzerdefinierten Dokumentserializer zu erstellen, der die ISwaggerDocumentSerializer -Schnittstelle implementiert. Dies kann in den SwaggerOptions in der Servicesammlung mit ConfigureSwagger() festgelegt werden:

Notiz

Wenn Sie das Befehlszeilen -Tool verwenden möchten, um OpenAPI -Spezifikationsdateien zu generieren, muss dies in der Service -Sammlung mit ConfigureSwagger() erfolgen.

 services.configuresWagger (options => {option.setCustomDocumentSerializer <CustomdocumentSerializer> ();})

Wenn das Befehlszeilen -Tool nicht verwendet wird, kann es auch auf dem Anwendungshost erfolgen:

 app.useswagger (options => {options.setCustomDocumentSerializer <CustomdocumentSerializer> ();})

Swashbuckle.aspnetcore.swaggergen

Zuweisen explizite OperationIDs

In der Prahlerei können Operationen eine operationId zugewiesen werden. Diese ID muss unter allen in der API beschriebenen Operationen eindeutig sein. Tools und Bibliotheken (z. B. Client -Generatoren) können die Operation ID verwenden, um einen Vorgang eindeutig zu identifizieren. Daher wird empfohlen, gemeinsame Programmiernamenkonventionen zu befolgen.

Die automatische Generung einer ID, die diesen Anforderungen entspricht und gleichzeitig einen Namen angibt, der in Client-Bibliotheken aussagekräftig wäre, ist eine nicht triviale Aufgabe, und so lässt Swashbuckle die operationId standardmäßig aus. Bei Bedarf können Sie jedoch operationIds zuweisen, indem Sie einzelne Routen dekorieren oder eine benutzerdefinierte Strategie bereitstellen.

Option 1) Dekorieren Sie die Routen mit einer Name

 [Httpget ("{id}", name = "getProductbyId")] public iactionResult get (int id) // operationID = "getProductbyId"

Option 2) eine benutzerdefinierte Strategie angeben

 // startup.csservices.addswaggergen (c => {... // Methodenname als OperationID CustomoperationIDs (apidesc => {return apidesc.trygetMethodInfo (out methodinfo methodInfo)? MethodInfo.name: null;});}; ) // ProductsController.cs [httpget ("{id}")] public iActionResult getProductbyId (int id) // operationID = "getProductbyId"

HINWEIS: Bei beiden Ansätzen sind API -Autoren dafür verantwortlich, die Einzigartigkeit von operationIds über alle Operationen hinweg sicherzustellen

Listenbetriebantworten auflisten

Standardmäßig generiert Swashbuckle für jede Operation eine "200" -Reaktion. Wenn die Aktion eine Antwort DTO zurückgibt, wird dies verwendet, um ein Schema für den Reaktionskörper zu erzeugen. Zum Beispiel ...

 [Httppost ("{id}")] öffentliches Produkt getbyId (int id)

Erzeugt die folgenden Antwortmetadaten: 

responses: {
  200: {
    description: "OK",
    content: {
      "application/json": {
        schema: {
          $ref: "#/components/schemas/Product"
        }
      }
    }
  }
}

Explizite Antworten

Wenn Sie einen anderen Statuscode und/oder zusätzliche Antworten angeben müssen oder Ihre Aktionen IActionResult anstelle eines Antwort -DTO zurückgeben, können Sie die Antworten explizit mit dem ProducesResponseTypeAttribute beschreiben, der mit ASP.NET -Kern versendet wird. Zum Beispiel ...

 [Httppost ("{id}")] [produzierterSetype (TypeOf (Produkt), 200)] [produzierterType (TypeOF (IDictionary <String <String>), 400)] [ProducesResponSetype (500)] public iactionresult GetbyId (int id id)

Erzeugt die folgenden Antwortmetadaten: 

responses: {
  200: {
    description: "OK",
    content: {
      "application/json": {
        schema: {
          $ref: "#/components/schemas/Product"
        }
      }
    }
  },
  400: {
    description: "Bad Request",
    content: {
      "application/json": {
        schema: {
          type: "object",
          additionalProperties: {
            type: "string"
          }
        }
      }
    }
  },
  500: {
    description: "Internal Server Error",
    content: {}
  }
}

FLAGS erforderliche Parameter und Schemaeigenschaften

In einem Swagger -Dokument können Sie Parameter und Schema -Eigenschaften markieren, die für eine Anfrage erforderlich sind. Wenn ein Parameter (oberste Ebene oder Eigenschaftsbasis) mit der BindRequiredAttribute oder RequiredAttribute dekoriert ist, markiert Swashbuckle ihn automatisch als "Erforderliche" Parameter in der generierten Prahlerei:

 // ProductsController.cspublic iActionResult -Suche ([FromQuery, BindRequired] String -Schlüsselwörter, [FromQuery] PagingParams PagingParams) {if (! ModelState.isvalid) return badRequest (ModelState); ] public int pageno {get; Satz; } public int pageSize {get; Satz; }}

Zusätzlich zu den Parametern wird Swashbuckle auch die RequiredAttribute ehren, wenn sie in einem Modell verwendet wird, das an die Anforderungskörper gebunden ist. In diesem Fall werden die dekorierten Eigenschaften als "erforderliche" Eigenschaften in der Körperbeschreibung gekennzeichnet:

 // ProductsController.cspublic iActctionResult CREATE ([From Body] Product Product) {if (! ModelState.isvalid) return badRequest (modelState); Satz; } öffentliche Zeichenfolge Beschreibung {get; Satz; }}

Behandeln Sie Formulare und Datei -Uploads

Dieser Controller akzeptiert zwei Formularfeldwerte und ein benannter Datei -Upload aus demselben Formular:

 [Httppost] public void uploadFile ([FromForm] String Beschreibung, [FromForm] DateTime ClientDate, iFormFile -Datei)

Wichtiger Anmerkung: Gemäß den ASP.NET -Kerndokumenten sollten Sie die Parameter IFormFile mit dem Attribut [FromForm] nicht dekorieren, da die Bindungsquelle automatisch aus dem Typ abgeleitet wird. Tatsächlich ist der abgeleitete Wert BindingSource.FormFile und wenn Sie das Attribut anwenden, wird er stattdessen auf BindingSource.Form eingestellt, das ApiExplorer vermasselt, der Metadatenkomponente, die mit ASP.NET -Kern versendet wird und stark von SWASHBIGLE angewiesen ist. Ein bestimmtes Problem ist hier, dass Swaggerui den Parameter nicht als Datei behandelt und daher keine Datei -Upload -Schaltfläche angezeigt wird, wenn Sie dieses Attribut fälschlicherweise angeben.

Datei -Downloads verarbeiten

ApiExplorer (die ASP.NET -Core -Metadatenkomponente, auf der Swashbuckle basiert) erscheint die FileResult -Typen standardmäßig nicht und Sie müssen es mit dem Attribut ProducesResponseType -Attribut (oder Produces auf .NET 5 oder älter) ausdrücklich mitteilen:

 [Httpget ("{fileName}")] [produziert

Beschreibungen aus XML -Kommentaren eingeben

Um die generierten Dokumente mit menschenfreundlichen Beschreibungen zu verbessern, können Sie Controller-Aktionen und -modelle mit XML-Kommentaren kommentieren und Swashbuckle so konfigurieren, dass diese Kommentare in den ausgegebenen Swagger JSON einbezogen werden:

  1. Öffnen Sie das Dialogfeld "Eigenschaften" für Ihr Projekt, klicken Sie auf die Registerkarte "Erstellen" und stellen Sie sicher, dass "XML -Dokumentationsdatei" überprüft wird, oder fügen Sie <GenerateDocumentationFile>true</GenerateDocumentationFile> Element in den Abschnitt <PropertyGroup> in Ihrem .csproj -Projektdatei hinzu. Dadurch wird eine Datei mit allen XML-Kommentaren zur Erstellungszeit erstellt.

    Zu diesem Zeitpunkt werden alle Klassen oder Methoden, die nicht mit XML -Kommentaren kommentiert werden, eine Build -Warnung auslösen. Um dies zu unterdrücken, geben Sie den Warncode "1591" in das Feld "Unterdrückung Warnungen" im Dialogfeld "Eigenschaften" ein oder fügen Sie <NoWarn>1591</NoWarn> zum Abschnitt <PropertyGroup> in Ihrer .csproj -Projektdatei hinzu.

  2. Konfigurieren Sie Swashbuckle, um die XML -Kommentare in Datei in den generierten Prahler -JSON einzubeziehen:

     Services.addswaggergen (c => {C.Swaggerdoc ("v1", New OpenAPIInfo {title = "my api - v1", Version = "v1"}); c.includexmlComments (Typof (MyController) .Assembly));}

  3. Anmerkende Ihre Aktionen mit Zusammenfassung, Bemerkungen, Paramien- und Antwort -Tags:

     /// <summary> /// ruft ein bestimmtes Produkt nach eindeutiger ID /// </summary> /// <Anmerkungen> Awesomeness! > Die Produkt -ID </param> /// <Antwortcode = "200"> Produkt abgerufen </Antwort "500"> Ups! Sie können Ihr Produkt im Moment nicht suchen </response> [httpget ("{id}")] [produziert Ausweis)

  4. Sie können auch Typen mit Zusammenfassung und Beispiel -Tags kommentieren:

     Public Class Product {/// <summary> /// Der Name des Produkts /// </summary> /// <beispiels> Männerbasketballschuhe für Männer </Beispiel> public String Name {get; Satz; } /// <summary> /// Quantität in Lagerbestand gelassen /// </summary> /// <beispiel> 10 </Beispiel> public intableStock {get; Satz; } /// <summary> /// Die Größen Das Produkt ist in /// </summary> /// <beispiel> ["klein", "Medium", "groß"] </Beispiel> öffentliche Liste < String> Größen {get; Satz; }}

  5. Bauen Sie Ihr Projekt neu auf, um die XML -Kommentare -Datei zu aktualisieren und zum Swagger JSON -Endpunkt zu navigieren. Beachten Sie, wie die Beschreibungen auf entsprechende Prahlerfelder zugeordnet werden.

HINWEIS: Sie können auch Beschreibungen des Swagger -Schemas bereitstellen, indem Sie Ihre API -Modelle und deren Eigenschaften mit zusammenfassenden Tags annotieren. Wenn Sie über mehrere XML -Kommentaredateien (z. B. separate Bibliotheken für Controller und Modelle) verfügen, können Sie die IncludexML -Datenmethode mehrmals aufrufen und alle werden in den ausgegebenen Swagger JSON zusammengefasst.

Stellen Sie globale API -Metadaten zur Verfügung

Zusätzlich zu "Pathitems", "Operations" und "Antworten", die Swashbuckle für Sie generiert, unterstützt Swagger auch globale Metadaten (siehe https://swagger.io/specification/#oasobject). Beispielsweise können Sie eine vollständige Beschreibung für Ihre API, die Nutzungsbedingungen oder sogar Kontakt- und Lizenzinformationen bereitstellen:

 C.Swaggerdoc ("v1", neue OpenAPIInfo {title = "my api - v1", Version = "v1", Beschreibung = "Eine Beispiel -API für Demo Swashbuckle", TermsOfService = new uri ("http://tempuri.org /Begriffe "), contact = new OpenAPICONTACT {name =" Joe Developer ", E -Mail =" [email protected] "}, lizenz = new openAPilicense {name =" apache 2.0 ", url = new URI (" https: "https:" //www.apache.org/licenses/license-2.0.html ")}});

Tipp: Verwenden Sie Intellisense, um zu sehen, welche anderen Felder verfügbar sind.

Generieren Sie mehrere Prahlerin -Dokumente

Mit dem oben beschriebenen Setup enthält der Generator alle API -Operationen in einem einzigen Swagger -Dokument. Sie können jedoch bei Bedarf mehrere Dokumente erstellen. Sie möchten beispielsweise ein separates Dokument für jede Version Ihrer API. Beginnen Sie dazu mit zunehmendem Definieren mehrerer Dokumente in Startup.cs :

 Services.Addswaggergen (c => {C.Swaggerdoc ("v1", New OpenAPIInfo {title = "my api - v1", Version = "v1"}); Meine API - v2 ", Version =" v2 "});})

Beachten Sie das erste Argument für Swaggerdoc. Es muss ein uri-freundlicher Name sein, der das Dokument eindeutig identifiziert. Anschließend wird es verwendet, um den Pfad für die Anforderung des entsprechenden Prahlerei JSON zu bestimmen. Beispielsweise werden mit dem Standardrouting die oben genannten Dokumente unter "/Swagger/v1/swagger.json" und "/Wagger/v2/swagger.json" verfügbar sein.

Als nächstes müssen Sie Swashbuckle informieren, welche Aktionen in jedes Dokument aufgenommen werden sollen. Obwohl dies angepasst werden kann (siehe unten), verwendet der Generator standardmäßig die Eigenschaft ApiDescription.GroupName , Teil der integrierten Metadatenschicht, die mit ASP.NET-Kern versendet wird, um diese Unterscheidung zu treffen. Sie können dies durch Dekorieren individueller Aktionen oder durch Anwenden einer anwendungsweiten Konvention festlegen.

Individuelle Handlungen dekorieren

Um eine Aktion in ein bestimmtes Swagger -Dokument aufzunehmen, dekorieren Sie sie mit dem ApiExplorerSettingsAttribute und setzen Sie GroupName auf den entsprechenden Dokumentnamen (Fallempfindlichkeit):

 [Httppost] [apiexplorersettings (GroupName = "v2")] öffentlicher void Post ([From Body] Produktprodukt)

Dokumente nach Übereinkommen Aktionen zuweisen

Um nach Übereinkommen zu gruppieren, anstatt jede Aktion zu dekorieren, können Sie einen benutzerdefinierten Controller oder eine Aktionskonvention anwenden. Sie können beispielsweise die folgende Konvention verkabeln, um Aktionen an Dokumente zuzuweisen, die auf dem Controller -Namespace basieren.

 // apiexPlorerGroupperversionConvention.CSPUBLIC CLASS APIEXPLORERGROUPERVERSIONCONIVENTION: ICONTROLLMODELCONIVENTION {public void anwenden (ControllModel Controller) {var controllerNameSpace = Controller.ControllerType.namesspace; // EG "Controller.v1" var apiversion = controllernamePace.split ('.'). Services.Addmvc (c => conventions.add (neue ApiexplorerGroupperversionConvention ()); ...}

Passen Sie den Aktionsauswahlprozess an

Bei der Auswahl von Aktionen für ein bestimmtes Swagger -Dokument ruft der Generator ein DocInclusionPredicate gegen jede ApiDescription auf, die vom Rahmen aufgetaucht ist. Die Standard -Implementierung inspiziert ApiDescription.GroupName . Sie können jedoch auch ein individuelles Einschlussprädikat bereitstellen. Wenn Sie beispielsweise einen attributbasierten Ansatz zur Implementierung von API-Versionen verwenden (z.

 C.DocinClusionPredicate (((docname, apidesc) => {if (! apidesc.trygetMethodinfo (out methodInfo methodinfo) return false; var varversions = methodeInfo.declingType .getCustomattributes (true) .Oftype <apiversimStrize> (). > attr.versions);

Mehrfachdokumente über die Benutzeroberfläche freigeben

Wenn Sie die SwaggerUI Middleware verwenden, müssen Sie zusätzliche Prahler -Endpunkte angeben, die Sie freilegen möchten. Weitere Informationen finden Sie in mehreren Swagger -Dokumenten.

Veraltete Operationen und/oder Schema -Eigenschaften auslassen

Die Swagger -Spezifikation enthält ein deprecated Flag, um anzuzeigen, dass eine Operation veraltet ist und von der Verwendung nicht verwendet werden sollte. Der Prahlergenerator setzt dieses Flag automatisch, wenn die entsprechende Aktion mit dem ObsoleteAttribute dekoriert ist. Anstatt ein Flag festzulegen, können Sie den Generator so konfigurieren, dass er veraltete Aktionen insgesamt ignorieren:

 Services.addswaggergen (c => {... C.InnoreObsoleTeactions ();};

Ein ähnlicher Ansatz kann auch verwendet werden, um veraltete Eigenschaften von Schemata in der Prahlerei abzulassen. Das heißt, Sie können die Modelleigenschaften mit der ObsoleteAttribute dekorieren und Swashbuckle konfigurieren, um diese Eigenschaften beim Generieren von JSON -Schemas wegzulassen:

 Services.AddsWaggergen (c => {... C.InnoreObsoleTeProperties ();};

Willkürliche Operationen weglassen

Sie können Operationen aus der Swagger -Ausgabe weglassen, indem Sie individuelle Aktionen dekorieren oder eine anwendungsweite Konvention anwenden.

Individuelle Handlungen dekorieren

Um eine bestimmte Aktion wegzulassen, dekorieren Sie sie mit der ApiExplorerSettingsAttribute und setzen Sie die IgnoreApi -Flagge:

 [Httpget ("{id}")] [apiexplorersettings (ignoreapi = true)] öffentliches Produkt getbyId (int id)

Handlungen durch Konvention auslassen

Um Aktionen durch Konvention wegzulassen, anstatt sie einzeln zu dekorieren, können Sie eine benutzerdefinierte Aktionskonvention anwenden. Sie können beispielsweise die folgende Konvention verkabeln, um nur Operationen zu dokumentieren:

 // apiexPlorergetonlyConvention.CSPUBLIC CLASS APIEXPLOREGERGETONLYCONIVENTION: IActionModelConvention {public void anwenden (actionModel action) {action.apiexPlorer Effekt dienste) {dienste.addmvc (c => conventions.add (neue ApiexPlorergetonlyConvention ())); ...}

Anpassen von Betriebs -Tags (z. B. für die UI -Gruppierung)

Mit der Swagger -Spezifikation können ein oder mehrere "Tags" einer Operation zugewiesen werden. Der Swagger -Generator weist den Controller -Namen als Standard -Tag zu. Dies ist wichtig zu beachten, ob Sie die SwaggerUI Middleware verwenden, da dieser Wert für Gruppenoperationen verwendet wird.

Sie können das Standard -Tag überschreiben, indem Sie eine Funktion bereitstellen, die Tags nach Übereinkommen anwendet. Beispielsweise wird die folgende Konfiguration nach HTTP -Methode markiert und damit Gruppenoperationen in der Benutzeroberfläche in der Benutzeroberfläche markiert:

 Services.addsWaggergen (c => {... c. -TagactionsBy (api => api.httpMethod);};

Operation Sortierreihenfolge ändern (z. B. für die UI -Sortierung)

Standardmäßig werden Aktionen nach dem zugewiesenen Tag (siehe oben) bestellt, bevor sie in die path-zentrierte, verschachtelte Struktur der Swagger-Spezifikation eingeteilt werden. Sie können jedoch die Standardordnung von Aktionen mit einer benutzerdefinierten Sortierstrategie ändern:

 Services.addsWaggergen (c => {... c.OrdactionsBy ((apidesc) => $ "{apidesc.actiondescriptor.routeValues ​​[" Controller "]} _ {apidesc.httpMethod}");};

Hinweis: Dies bestimmt die Sortierreihenfolge, bevor die Aktionen gruppiert und in das Prahlerformat umgewandelt werden. Es wirkt sich also auf die Reihenfolge von Gruppen (dh Prahlerei "Pathitems") und die Reihenfolge der Operationen innerhalb einer Gruppe in der Prahlerei aus.

Passen Sie Schema -IDs an

Wenn der Generator auf komplexen Parameter oder Antworttypen stößt, generiert er ein entsprechendes JSON -Schema, fügen Sie es zu den globalen components/schemas -Wörterbuchs und verweisen Sie aus der Operation Beschreibung durch eindeutige ID. Wenn Sie beispielsweise eine Aktion haben, die einen Product zurückgibt, wird das generierte Schema wie folgt verwiesen: 

responses: {
  200: {
    description: "OK",
    content: {
      "application/json": {
        schema: {
          $ref: "#/components/schemas/Product"
        }
      }
    }
  }
}

Wenn es jedoch auf mehrere Typen mit demselben Namen, aber unterschiedlichen Namespaces (z. B. RequestModels.Product & ResponseModels.Product ) stößt, erhöht Swashbuckle aufgrund von "widersprüchlichen Schemaids" eine Ausnahme. In diesem Fall müssen Sie eine benutzerdefinierte ID -Strategie bereitstellen, die den Namen weiter qualifiziert:

 Services.addswaggergen (c => {... customSchemaids ((Typ) => type.fullname);};

In #2703 finden Sie Unterstützung für verschachtelte Typen.

Schema für bestimmte Typen überschreiben

Swashbuckle leistet eine angemessene Aufgabe, JSON-Schemas zu generieren, die Ihre Anfrage- und Antwortnutzlasten genau beschreiben. Wenn Sie jedoch das Serialisierungsverhalten für bestimmte Typen in Ihrer API anpassen, müssen Sie möglicherweise helfen.

Zum Beispiel haben Sie möglicherweise eine Klasse mit mehreren Eigenschaften, die Sie in JSON als von Kommas getrennte Zeichenfolge darstellen möchten. Dazu würden Sie wahrscheinlich einen benutzerdefinierten JsonConverter implementieren. In diesem Fall weiß Swashbuckle nicht, wie der Konverter implementiert ist, und Sie müssen ihm ein Schema zur Verfügung stellen, das den Typ genau beschreibt:

 // PhoneNumber.cspublic Class PhoneNumber {public String CountryCode {get; Satz; } public String AreaCode {get; Satz; } public String subscriberid {get; Satz; }} // startup.csServices.addswaggergen (c => {... c.maptype <phoneNumber> (() => new OpenAnchema {type = "string"});};

Generator mit Betriebs-, Schema- und Dokumentfiltern erweitern

Swashbuckle enthält eine Filterpipeline, die sich in den Erzeugungsprozess anschließt. Nach der Erzeugung werden einzelne Metadatenobjekte in die Pipeline übergeben, wo sie weiter geändert werden können. Sie können benutzerdefinierte Filter verkabeln, um die generierten "Operationen", "Schemas" und "Dokumente" zu bereichern.

Betriebsfilter

Swashbuckle holt für jede Aktion eine ApiDescription , Teil des ASP.NET -Kerns und generiert sie, um eine entsprechende OpenApiOperation zu erzeugen. Nach der Erstellung wird die OpenApiOperation und die ApiDescription über die Liste der konfigurierten Betriebsfilter geleitet.

In einer typischen Filter -Implementierung werden die ApiDescription auf relevante Informationen (z. B. Routeninformationen, Aktionattribute usw.) untersucht und dann die OpenApiOperation entsprechend aktualisieren. Beispielsweise listet der folgende Filter eine zusätzliche Antwort "401" für alle Aktionen auf, die mit der AuthorizeAttribute dekoriert sind:

 // AuthresponseoperationFilter.CSPUBLIC CLASSE AUTHREPONSOPERATIONSFILTER: IOPERATIONSFILTER {public void anwenden (OpenAPIOPERATIONS -OPTER, OPERTFILTERCONTEXT) {var Authatattributes). Oftype <AuthorizeAttribute > (); if (authatTributes.anan ()) operation.responses.add ("401", neue OpenAPIPResponse {Beschreibung = "Unauthorized"});}} // startup.csservices.addswaggergen (c => {... C.operationFilter <authresponSeSoperationFilter> ();};

HINWEIS: Filterpipelines sind di-bewusst. Das heißt

Schemafilter

Swashbuckle erzeugt ein Json-Schema mit Swagger-Geschmack für jeden Parameter, jede Antwort und jeden Eigenschaftstyp, der durch Ihre Controller-Aktionen ausgesetzt ist. Nach der Erstellung führt es das Schema und tippt die Liste der konfigurierten Schemafilter durch.

Das folgende Beispiel fügt eine Autorest-Anbieter-Erweiterung hinzu (siehe https://github.com/azure/utorest/blob/master/docs/extensions/readme.md#x-ms-num), um das Autorest-Tool zu informieren, wie Enums modelliert werden sollten Wenn es den API -Client erzeugt.

 // AutoRestSchemaFilter.cspublic class AutoRestSchemaFilter : ISchemaFilter{public void Apply(OpenApiSchema schema, SchemaFilterContext context){var type = context.Type;if (type.IsEnum){schema.Extensions.Add("x-ms-enum",new OpenAPIObject {["name"] = new OpenAPISTRING (type.name), ["modelAsstring"] = new OpenABOOLEAN (TRUE)});};}} // startup.csservices.addswaggergen (c => {... c .Schemafilter <autorestschemafilter> ();};

Das folgende Beispiel ermöglicht die automatische Schema -Erzeugung von generischen Dictionary<Enum, TValue> Objekten. Beachten Sie, dass dies nur die Prahlerei erzeugt; System.Text.Json ist standardmäßig nicht in der Lage, die Wörterbuch -Enums zu analysieren, sodass Sie wie in den .NET -Dokumenten einen speziellen JsonConverter benötigen

 // DictionarytkeyEnumTValueSchemafilter.Cspublic Class DictionarytkeyEnumTValueschemafilter: Ischemafilter {
  Öffentliche Void anwenden (OpenAPischema -Schema, SchemafilterContext -Kontext)
  {// nur für Felder ausführen, die ein Wörterbuch <enum, tvalue> if (! Context.type.isgenerictpe ||! Context.type.getGenericpedEfinition (). var keytype = context.type.getgenericArgumente () [0]; var Valuetype = context.type.getGenericArgumente () [1]; if (! keytype.issenum) {return;} schema.type = "Objekt"; Schema.Properties = keytype.getEnnumnamen ().
  }} // startup.csservices.addswaggergen (c => {... // Diese werden durch DictionaryTkeyEnumTValueSchemafilter ersetzt, werden jedoch benötigt, um einen Fehler zu vermeiden.// Sie benötigen eine für jede Art von Wörterbuch <,> Sie haben .C.Maptype <Dictionary <myenum, list <String >>> (() => new OpenAnchema ());

Dokumentfilter

Sobald ein OpenApiDocument erzeugt wurde, kann auch es durch eine Reihe von vorkonfigurierten Dokumentfiltern geleitet werden. Dies gibt eine vollständige Kontrolle, um das Dokument zu ändern, wie Sie es für Anpassung ansehen. Um sicherzustellen, dass Sie weiterhin gültige Prahlerei JSON zurückgeben, sollten Sie die Spezifikation lesen, bevor Sie diesen Filtertyp verwenden.

Das folgende Beispiel enthält eine Beschreibung für Tags, die den Vorgängen im Dokument zugewiesen sind:

 public class tagdescriptionsdocumentFilter: idocumentFilter {public void anwenden (OpenAPIDOCument SwaggerDoc, Konzert {Name = "Bestellungen", Beschreibung = "Bestellungen senden"}};}}

Hinweis: Wenn Sie die SwaggerUI Middleware verwenden, kann der oben gezeigte TagDescriptionsDocumentFilter verwendet werden, um zusätzliche Beschreibungen neben jeder Operationsgruppe anzuzeigen.

Fügen Sie Sicherheitsdefinitionen und Anforderungen hinzu

In Swagger können Sie beschreiben, wie Ihre API durch Definieren eines oder mehrere Sicherheitsschemata (z. B. Basic, API -Schlüssel, OAuth2 usw.) und der Erklärung, welche dieser Systeme global oder für bestimmte Operationen anwendbar sind, definiert werden. Weitere Informationen finden Sie in der Swagger Spec.

In Swashbuckle können Sie Systeme definieren, indem Sie die AddSecurityDefinition -Methode aufrufen und einen Namen und eine Instanz von OpenApiSecurityScheme angeben. Zum Beispiel können Sie einen OAuth 2.0 - impliziten Fluss wie folgt definieren:

 // startup.csservices.addswaggergen (c => {... // Definieren Sie das OATH2.0 -Schema, das verwendet wird (dh impliziten Fluss). NEU OpenAPIOAUTHFLOWS {Implicit = new OpenAPIOAUTHFLOW {Authorizationurl = new URI ("/Auth-Server/Connect/Autorize", Urikind.Relative), Scopes = new Dictionary <String, String> {{"ReadAccess", "Zugriff auf Operationen , {"WriteAccess", "Zugriff auf Schreibvorgänge"}}}}});};

Hinweis: Zusätzlich zur Definition eines Schemas müssen Sie auch angeben, auf welche Vorgänge dieses Schema anwendbar sind. Sie können Schemata (dh alle Operationen) weltweit über die AddSecurityRequirement -Methode anwenden. Das folgende Beispiel zeigt an, dass das Schema mit dem Namen "OAuth2" auf alle Operationen angewendet werden sollte und dass die "Readaccess" und "WriteAccess" -Plüte erforderlich sind. Wenn Sie andere Typen als "oAuth2" anwenden, muss das Array der Bereiche leer sein.

 C.Addswaggergen (c => {... C.AddSecurityRequirement (new OpenAPISecurityRequirement {{new OpenAPIecurityscheme {reference = new OpenAPireference {type = Referencetype.securityscheme, Id = "OATH2"}}, new [] {"{" {"{" {"{" {"{" {"{" {"{" {"{" {"{" {"{" {"{" {"{" {"{" {"{" {"{" {"{" {"readAcal", "," WriteAccess "}}});})

Wenn Sie Systeme haben, die nur für bestimmte Vorgänge anwendbar sind, können Sie sie über einen Betriebsfilter anwenden. Zum Beispiel fügt der folgende Filter die OAuth2 -Anforderungen hinzu, die auf der Anwesenheit der AuthorizeAttribute basieren:

 // SecurityRequirementsOperationFilter.CSPUBLIC CLASSE STEACTIONREQUIRMENTSOPERATIONSFILTER: IOPERATIONSFILTER {public void anwenden (OpenAPIOperation Operation, OperationFilterContext -Kontext) {// Richtliniennamen map to Scopesvar fordertscopes = context.methodinfo.getObUbUbUtOntomat () (echte) (echte) (echte) (echte) (echte) (echte) (echte) (echte) (echte) (echte) (echte) (echte) (echte) (echte) (echte) (echte) (echte) (echte) (echte) (echte) (echte) (echte) (echte) (echte) > attr.policy) .distinct (); if (forderscopes.anan ()) {operation.responses.add ("401", New OpenAPIResponse {Beschreibung = "Nicht autorisiert"}); Operation.responses.add ("403",, NEU OpenAPIResponse {Beschreibung = "Forbidden"}); var oauthscheme = new OpenAPIeCurityScheme {reference = new OpenAPireference {type = referencetype.securityScheme, id = "oAuth2"}; Operation OAuthScheme] = fordersScopes.tolist ()}};}}}

Hinweis: Wenn Sie die SwaggerUI Middleware verwenden, können Sie interaktive OAuth2.0 -Flows aktivieren, die von den emittierten Sicherheitsmetadaten betrieben werden. Weitere Informationen finden Sie unter Aktivieren von OAuth2.0 -Strömen.

Fügen Sie Sicherheitsdefinitionen und Anforderungen für Trägerauth hinzu

 Services.Addswaggergen (c => {C.AddSecurityDefinition ("BearerAuth", New OpenApisecurityScheme {type = SecuritySchemetype.http, Scheme = "Bearer", BearerFormat = "jwt", Beschreibung = "JWT -Autorisierungs -Header verwendet das Bearer -Schema."}. "}."}. "}."}. "}."}. );

Vererbung und Polymorphismus

Swagger / OpenAPI definiert die allOf und oneOf -Schlüsselwörtern zur Beschreibung der Vererbungs- und Polymorphismus -Beziehungen in Schemadefinitionen. Wenn Sie beispielsweise eine Basisklasse für Modelle verwenden, die gemeinsame Eigenschaften gemeinsam haben, können Sie das allOf -Schlüsselwort verwenden, um die Erbschaftshierarchie zu beschreiben. Oder wenn Ihr Serializer die polymorphe Serialisierung/Deserialisierung unterstützt, können Sie das oneOf -Schlüsselwort verwenden, um alle "möglichen" Schemata für Anforderungen/Antworten zu dokumentieren, die je nach Subtyp variieren.

Erbschaft ermöglichen

Standardmäßig flacht Swashbuckle die Erbhierarchien. Das heißt, für abgeleitete Modelle werden die ererbten Eigenschaften zusammen mit den deklarierten Eigenschaften kombiniert und aufgeführt. Dies kann in der erzeugten Prahlerei viel Duplikation verursachen, insbesondere wenn mehrere Subtypen vorhanden sind. Es ist auch problematisch, wenn Sie einen Client -Generator (z. B. NSWAG) verwenden und die Erbschafthierarchie in den generierten Client -Modellen beibehalten möchten. Um dies zu umgehen, können Sie die Einstellung UseAllOfForInheritance anwenden, und dies nutzt das allOf -Schlüsselwort, um vererbte Eigenschaften durch Referenz in die generierte Prahlerei einzubeziehen: 

Circle: {
  type: "object",
  allOf: [
    {
      $ref: "#/components/schemas/Shape"
    }
  ],
  properties: {
    radius: {
      type: "integer",
      format: "int32",
    }
  },
},
Shape: {
  type: "object",
  properties: {
    name: {
      type: "string",
      nullable: true,
    }
  },
}

Polymorphismus ermöglichen

Wenn Ihr Serializer die polymorphe Serialisierung/Deserialisierung unterstützt und Sie die möglichen Subtypen für eine Aktion auflisten möchten, die abstrakte Basistypen akzeptiert/zurückgibt, können Sie die Einstellung UseOneOfForPolymorphism anwenden. Infolgedessen verweist die generierten Anforderungs-/Antwortschemata auf eine Sammlung von "möglichen" Schemata anstelle des Basisklassenschemas: 

requestBody: {
  content: {
    application/json: {
      schema: {
      oneOf: [
        {
          $ref: "#/components/schemas/Rectangle"
        },
        {
          $ref: "#/components/schemas/Circle"
        },
      ],
    }
  }
}

Erkennen von Subtypen

Da Vererbungs- und Polymorphismus -Beziehungen nicht nur in Ihren eigenen Modellen, sondern auch in der .NET -Klassenbibliothek ziemlich komplex werden können. Standardmäßig werden alle Subtypen aufgenommen, die in derselben Baugruppe wie einen bestimmten Basistyp definiert sind. Wenn Sie dieses Verhalten überschreiben möchten, können Sie eine benutzerdefinierte Selektorfunktion angeben:

 Services.addswaggergen (c => {... C.UseAllofforinheritance (); C.SelectSuBTypeSused (BaseType => {return typeof (Startup) .Assembly.gettTypes (). WO (type => type.ISSubClassof (BaseType)); })});

Hinweis: Wenn Sie die Swashbuckle -Annotationsbibliothek verwenden, enthält sie einen benutzerdefinierten Selektor, der auf dem Vorhandensein von SwaggerSubType -Attributen zu Basisklassendefinitionen basiert. Auf diese Weise können Sie einfache Attribute verwenden, um die Vererbung und/oder Polymorphismus -Beziehungen, die Sie aufdecken möchten, explizit aufzulisten. Um dieses Verhalten zu ermöglichen, lesen Sie die Anmerkungsdokumente.

Diskriminatoren beschreiben

Swagger / OpenAPI unterstützt in Verbindung mit den oneOf und / oder allOf -Schlüsselwörtern ein discriminator für Basisschema -Definitionen. Dieses Schlüsselwort verweist auf die Eigenschaft, die den spezifischen Typ identifiziert, der durch eine bestimmte Nutzlast dargestellt wird. Zusätzlich zum Eigenschaftsnamen kann die Beschreibung des Diskriminators auch eine mapping enthalten, die Diskriminatorwerte auf bestimmte Schema -Definitionen abstellt.

Beispielsweise unterstützt der Newtonsoft Serializer die polymorphe Serialisierung/Deserialisierung, indem sie eine Eigenschaft "$ tyty" in JSON -Instanzen emittieren/akzeptiert. Der Wert dieser Eigenschaft ist der qualifizierte Typ -Name des Versammlungstyps des Typs, der durch eine bestimmte JSON -Instanz dargestellt wird. Um dieses Verhalten in der Prahlerei explizit zu beschreiben, könnte das entsprechende Anforderungs-/Antwortschema wie folgt definiert werden: 

components: {
  schemas: {
    Shape: {
      required: [
        "$type"
      ],
      type: "object",
      properties: {
        $type: {
          type": "string"
      },
      discriminator: {
        propertyName: "$type",
        mapping: {
          Rectangle: "#/components/schemas/Rectangle",
          Circle: "#/components/schemas/Circle"
        }
      }
    },
    Rectangle: {
      type: "object",
      allOf: [
        {
          "$ref": "#/components/schemas/Shape"
        }
      ],
      ...
    },
    Circle: {
      type: "object",
      allOf: [
        {
          "$ref": "#/components/schemas/Shape"
        }
      ],
      ...
    }
  }
}

Wenn UseAllOfForInheritance oder UseOneOfForPolymorphism aktiviert ist und Ihr Serializer eine Diskriminatoreigenschaft unterstützt (und hat aktiviert), generiert Swashbuckle automatisch die entsprechenden discriminator -Metadaten auf Basisschema -Definitionen.

Wenn Sie Ihren Serializer so angepasst haben, dass die polymorphe Serialisierung/Deserialisierung unterstützt wird, können Sie einige benutzerdefinierte Selektorfunktionen bereitstellen, um den Namen des Diskriminators und die entsprechende Zuordnung zu bestimmen:

 Services.AddsWaggergen (c => {... C.UseoneOfforinheritance ();

Hinweis: Wenn Sie die Swashbuckle -Annotationsbibliothek verwenden, enthält sie benutzerdefinierte Selektorfunktionen, die auf dem Vorhandensein von SwaggerDiscriminator und SwaggerSubType -Attributen zu Basisunterrichtsdefinitionen basieren. Auf diese Weise können Sie einfache Attribute verwenden, um explizit Diskriminatormetadaten bereitzustellen. Um dieses Verhalten zu ermöglichen, lesen Sie die Anmerkungsdokumente.

Swashbuckle.aspnetcore.swaggerui

Änderung des relativen Weges zur Benutzeroberfläche

Standardmäßig wird die UI der Prahlerei bei "/Swagger" freigelegt. Bei Bedarf können Sie dies ändern, wenn Sie die Swaggerui Middleware aktivieren:

 app.useswaggerui (c => {c.Routeprefix = "api-docs"}

Dokumenttitel ändern

Standardmäßig wird die Swagger -Benutzeroberfläche einen generischen Dokumenttitel haben. Wenn Sie mehrere Prahler -Seiten geöffnet haben, kann es schwierig sein, sie zu unterscheiden. Sie können dies ändern, wenn Sie die Swaggerui Middleware aktivieren:

 app.useswaggerui (c => {c.documentTitle = "Meine Prahlerei ui";}

Ändern Sie CSS- oder JS -Pfade

Standardmäßig umfasst die Swagger -Benutzeroberfläche Standard -CSS und JS. Wenn Sie jedoch den Pfad oder die URL ändern möchten (z. B. um eine CDN zu verwenden):

 app.useswaggerui (c => {c.stylesPath = "https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.17.10/swagger-ui.min.css"; : //cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.17.10/swagger-ui-bundle.min.js "; /swagger-ui/5.17.10/swagger-ui standalone-preset.min.js ";}

Listen Sie mehrere Prahlerin -Dokumente auf

Wenn Sie die Middleware aktivieren, müssen Sie einen oder mehrere Prahlerendpunkte (vollständig qualifiziert oder relativ zur UI -Seite) angeben, um die Benutzeroberfläche mit Strom zu versorgen. Wenn Sie mehrere Endpunkte bereitstellen, werden diese in der oberen rechten Ecke der Seite aufgeführt, sodass Benutzer zwischen den verschiedenen Dokumenten umschalten können. Beispielsweise könnte die folgende Konfiguration verwendet werden, um verschiedene Versionen einer API zu dokumentieren.

 app.useswaggerui (c => {c.swaggerendpoint ("/Swagger/v1/Swagger.json", "v1 docs"); }

Wenden Sie Swagger-UI-Parameter an

Die Swagger-UI wird mit eigenen Konfigurationsparametern geliefert, die alle hier beschrieben werden. In Swashbuckle sind die meisten von den Swaggerui Middleware -Optionen aufgetaucht:

 app.useswaggerui (c => {c.DefaultModelexpanddepth (2); Keine) c. ["MyCustOrgugin"]; ) => {Rückgabeantwort;} ");});

Notiz

Stellen Sie beim Hinzufügen benutzerdefinierter Plugins sicher, dass Sie benutzerdefinierte js -Dateien hinzufügen, die die Plugin -Funktion (en) definieren.

Benutzerdefinierte JavaScript injizieren

Um das Verhalten zu optimieren, können Sie zusätzliche JavaScript -Dateien injizieren, indem Sie sie Ihrem wwwroot -Ordner hinzufügen und die relativen Pfade in den Middleware -Optionen angeben:

 app.useswaggerui (c => {c.injectjavaScript ("/Swagger-ui/custom.js");};};

Hinweis: Die Optionen für InjectOnCompleteJavaScript und InjectOnFailureJavaScript wurden entfernt, da die neueste Version von Swagger-UI die erforderlichen Haken nicht freigibt. Stattdessen bietet es ein flexibles Anpassungssystem, das auf Konzepten und Mustern von React und Redux basiert. Um dies zu nutzen, müssen Sie eine benutzerdefinierte Version von index.html wie unten beschrieben bereitstellen.

Die benutzerdefinierte Index-Beispiel-App demonstriert diesen Ansatz, indem das Swagger-UI-Plugin-System verwendet wird, um eine benutzerdefinierte Topbar zu erhalten, und um die Info-Komponente auszublenden.

CSS injizieren

Um das Erscheinungsbild zu optimieren, können Sie zusätzliche CSS -Stylesheets injizieren, indem Sie sie Ihrem wwwroot -Ordner hinzufügen und die relativen Pfade in den Middleware -Optionen angeben:

 app.useswaggerui (c => {c.injectStylesheet ("/Swagger-ui/custom.css");};};

Passen Sie index.html an

Um die Benutzeroberfläche über die oben aufgeführten Grundoptionen hinaus anzupassen, können Sie Ihre eigene Version der Seite Swagger-UI Index.html bereitstellen:

 app.useswaggerUi (c => {c.indexstream = () => GettType ().

Um loszulegen, sollten Sie Ihren benutzerdefinierten index.html auf der Standardversion stützen

Aktivieren Sie OAuth2.0 Flows

Die Swagger-UI hat integrierte Unterstützung für die Teilnahme an OAuth2.0-Autorisierungsströmen. Es interagiert mit Autorisierungs- und/oder Token -Endpunkten, wie im Prahlerei JSON angegeben, um Zugriffstoken für nachfolgende API -Aufrufe zu erhalten. Siehe Hinzufügen von Sicherheitsdefinitionen und Anforderungen für ein Beispiel für das Hinzufügen von OAuth2.0 -Metadaten zur erzeugten Prahlerei.

Wenn Ihr Prahlerendpunkt die entsprechenden Sicherheitsmetadaten enthält, sollte die UI -Interaktion automatisch aktiviert werden. Sie können jedoch die OAuth -Unterstützung in der Benutzeroberfläche weiter mit den folgenden Einstellungen anpassen. Weitere Informationen finden Sie unter Swagger-UI-Dokumentation:

 app.useswaggerui (c => {c.oauthclientid ("test-id"); ); String, String> {{"foo", "bar"}});

Verwenden

Um benutzerdefinierte Interceptors für Anfragen und Antworten zu verwenden, die durch Swagger-UI gehen, können Sie sie in der Konfiguration als JavaScript-Funktionen definieren:

 app.useswaggerUi (c => {C.UseSequestInterceptor ("(req) => {req.Headers ['x-my-custom-header'] = 'mycustomValue'; return req;}"); (res) => {console.log ('benutzerdefinierte Interceptor -Abfang -Antwort von:', res.url);

Dies kann in einer Reihe von Szenarien nützlich sein, in denen Sie möglicherweise lokale XSRF -Token an alle Anfragen anhängen möchten, z. B. an alle Anfragen:

 app.USeswaggerUi (c => {c.UseSequestInterceptor ("(req) => {req.Headers ['x-xsrf-token'] = localStorage.getItem ('xsrf-token'); return req;}"); });

Swashbuckle.aspnetcore.Annotations

Anmerkungen installieren und aktivieren

  1. Installieren Sie das folgende Nuget -Paket in Ihrer ASP.NET -Kernanwendung. 

    Package Manager : Install-Package Swashbuckle.AspNetCore.Annotations
CLI : dotnet add package Swashbuckle.AspNetCore.Annotations

  2. Aktivieren Sie in der Methode für ConfigureServices von Startup.cs Anmerkungen innerhalb des Swagger -Konfigurationsblocks:

     Services.addswaggergen (c => {... C.EnableAnnotations ();});

AnArich Operation Metadata

Sobald Anmerkungen aktiviert sind, können Sie die generierten Betriebsmetadaten anreichern, indem Sie Aktionen mit einer SwaggerOperationAttribute dekorieren.

 [Httppost] [Swaggeroperation (summary = "Erstellt ein neues Produkt", Beschreibung = "Benötigt Admin -Privilegien", OperationID = "CreateProduct", Tags = new [] {"Kauf", "Produkte"}). From Body] Produktprodukt)

Anreicherung der Reaktionsmetadaten

ASP.NET CORE bietet die ProducesResponseTypeAttribute für die Auflistung der verschiedenen Antworten, die durch eine Aktion zurückgegeben werden können. Diese Attribute können wie oben beschrieben mit XML -Kommentaren kombiniert werden, um menschliche freundliche Beschreibungen mit jeder Antwort in der erzeugten Prahlerei einzubeziehen. Wenn Sie das alles mit einem einzigen Attribut vornehmen und die Verwendung von XML -Kommentaren vermeiden möchten, können Sie stattdessen SwaggerResponseAttribute S verwenden:

 [HTTPPOST] [SwaggerResponse (201, "Das Produkt wurde erstellt", Typof (Produkt)]] [SwaggerResponse (400, "Die Produktdaten sind ungültig")] öffentliche IActionResult Create ([From Body] Produktprodukt) Produktprodukte)

Anreicherung der Parametermetadaten

Sie können [FromQuery] Pfad SwaggerParameterAttribute , " [FromRoute] " oder "Header" gebundene Parameter oder Eigenschaften (z [FromHeader]

 [Httpget] public iactionResult -GetProducts ([FromQuery, SwaggerParameter ("Suchschlüsselwörter", fordert = true) String -Schlüsselwörter)

Enrich RequestBody Metadata

Sie können "Körper" gebundene Parameter RequestBody Eigenschaften ( [FromBody] SwaggerRequestBodyAttribute

 [HTTPPOST] Public IActionResult CreateProduct ([From Body, SwaggerRequestBody ("Die Produktnutzlast", erforderlich = wahr) Produktprodukt)

Anreicherungsschema -Metadaten

Sie können Klassen oder Eigenschaften mit einem SwaggerSchemaAttribute kommentieren, um die entsprechenden Schema -Metadaten zu bereichern, die von Swashbuckle erzeugt wird:

 [Swaggerschema (erforderlich = new [] {"Beschreibung"})] PUBLIC CLASSE -Produkt {[Swaggerschema ("The Product Identifier", readonly = true)] public int id {get; Satz; } [Swaggerschema ("die Produktbeschreibung")] public String Beschreibung {get; Satz; } [Swaggerschema ("Das Datum, das er erstellt wurde", format = "Datum")] public datetime datecroated {get; Satz; }}

Hinweis: In Swagger / OpenAPI werden serialisierte Objekte und enthaltene Eigenschaften als Schema -Instanzen dargestellt, weshalb diese Annotation sowohl auf Klassen als auch auf Eigenschaften angewendet werden kann. Auch erwähnenswert sind "erforderliche" Eigenschaften als eine Reihe von Eigenschaftsnamen auf dem Schema der obersten Ebene im Gegensatz zu einer Flagge auf jeder einzelnen Eigenschaft.

Wenden Sie Schemafilter auf bestimmte Typen an

Das SwaggerGen -Paket enthält mehrere Verlängerungspunkte, einschließlich Schemafilter (hier beschrieben) zum Anpassen aller generierten Schemas. Es kann jedoch Fälle geben, in denen es vorzuziehen ist, einen Filter auf ein bestimmtes Schema anzuwenden. Wenn Sie beispielsweise ein Beispiel für einen bestimmten Typ in Ihre API aufnehmen möchten. Dies kann durch Dekorieren des Typs mit einem SwaggerSchemaFilterAttribute erfolgen:

 // Product.cs [SwaggerSchemafilter (TypeOf (ProductsChemafilter)] PUBLIC CLASSE PRODUKT {...} // ProductsChemafilter.CSpublic Class Products ["Id"] = new openAPIinteger (1), ["Beschreibung"] = new OpenAPISTRING ("Ein fantastisches Produkt")};}}

Fügen Sie Tag -Metadaten hinzu

Standardmäßig markiert der Swagger -Generator alle Vorgänge mit dem Controller -Namen. Dieses Tag wird dann verwendet, um die Operation Groupings in der Swagger-UI zu fahren. Wenn Sie für jede dieser Gruppen eine Beschreibung angeben möchten, können Sie dies tun, indem Sie Metadaten für jedes Controller -Namensschild über das SwaggerTagAttribute hinzufügen:

 [Swaggertag ("Produkte erstellen, lesen, aktualisieren und löschen")] public Class ProductsController {...}

Hinweis: Dadurch wird die obige Beschreibung speziell zu dem Tag "Products" hinzugefügt. Daher sollten Sie es vermeiden, dieses Attribut zu verwenden, wenn Sie Operationen mit etwas anderem als dem Controller -Namen markieren - z. B. wenn Sie das Tagging -Verhalten mit TagActionsBy anpassen.

Listen Sie bekannte Subtypen für Vererbung und Polymorphismus auf

Wenn Sie Swashbuckles Erbe und/oder Polymorphismusverhalten verwenden möchten, können Sie Annotationen verwenden, um die "bekannten" Subtypen für einen bestimmten Basistyp explizit anzugeben. Dadurch wird die Standard -Selektorfunktion überschrieben, die alle Subtypen in derselben Baugruppe wie den Basistyp auswählt und daher explizit aktiviert werden muss, wenn Sie Anmerkungen aktivieren:

 // startup.csservices.addswaggergen (c => {C.EnableAnnotations (EnableAnnotationsforinheritanz: true, EnableAnnotationsforpolymorphismus: Richtig);}); // form.cs [Swaggersuubtype (typeof ] öffentliche abstrakte Klassenform {}

Angrößern polymorphe Basisklassen mit Diskriminatormetadaten

Wenn Sie Anmerkungen verwenden, um die "bekannten" Subtypen für einen polymorphen Basistyp explizit anzugeben, können Sie den SwaggerDiscriminatorAttribute mit dem SwaggerSubTypeAttribute kombinieren, um zusätzliche Metadaten über die Eigenschaft "Diskriminator" bereitzustellen, die dann in die erzeugte Schema -Definition eingebaut wird:

 // Startup.csservices.AddSwaggerGen(c =>{    c.EnableAnnotations(enableAnnotationsForInheritance: true, enableAnnotationsForPolymorphism: true);});// Shape.cs[SwaggerDiscriminator("shapeType")][SwaggerSubType(typeof(Rectangle), DiscriminatorValue = "Rechteck")] [SwaggersuBype (Typof (Kreis), DiskriminatorValue = "Circle")] öffentliche abstrakte Klasse Form {public Shapetype {get; Satz; }}

Dies weist darauf hin, dass die entsprechende Nutzlast eine "Shapetype" -Sache hat, die zwischen Subtypen unterscheidet, und dass die Eigenschaft einen Wert von "Rechteck" hat, wenn die Nutzlast einen Rectangle und einen Wert von "Kreis" darstellt, wenn er einen Circle darstellt. Dieses Detail wird in der generierten Schema -Definition wie folgt beschrieben: 

schema: {
  oneOf: [
    {
      $ref: "#/components/schemas/Rectangle"
    },
    {
      $ref: "#/components/schemas/Circle"
    },
  ],
  discriminator: {
    propertyName: shapeType,
    mapping: {
      rectangle: "#/components/schemas/Rectangle",
      circle: "#/components/schemas/Circle",
    }
  }
}

Swashbuckle.aspnetcore.cli

Rufen Sie Prahlerei direkt von einer Startversammlung ab

Sobald Ihre Bewerbung mit SWASHBICKLE eingerichtet wurde (siehe Einstieg), können Sie das SWASHBuckle CLI -Tool verwenden, um Swagger / OpenAPI JSON direkt aus der Startbaugruppe Ihrer Anwendung abzurufen und sie in die Datei zu schreiben. Dies kann nützlich sein, wenn Sie die Swagger-Generation in einen CI/CD-Prozess einbeziehen möchten oder wenn Sie sie zur Laufzeit aus der statischen Datei servieren möchten.

Es ist als .NET -Tool verpackt, das über den Dotnet SDK installiert und verwendet werden kann.

Euen Das Tool muss Ihre Start -DLL und seine Abhängigkeiten zur Laufzeit laden. Daher sollten Sie eine Version des dotnet -SDK verwenden, die mit Ihrer Anwendung kompatibel ist. Wenn Ihre App beispielsweise net6.0 abzielt, sollten Sie Version 6.0.xxx des SDK verwenden, um das CLI -Tool auszuführen. Wenn es auf net8.0 abzielt, sollten Sie Version 8.0.xxx des SDK usw. verwenden.

Verwenden des Tools mit dem .NET SDK

  1. Installieren Sie als globales Werkzeug 

    dotnet tool install -g Swashbuckle.AspNetCore.Cli

  2. Stellen Sie sicher, dass das Tool richtig installiert wurde 

    swagger tofile --help

  3. Generieren Sie ein Dokument für Prahlerei/ OpenAPI aus der Startbaugruppe Ihrer Anwendung 

    swagger tofile --output [output] [startupassembly] [swaggerdoc]

    Wo ...

    • [Ausgabe] ist der relative Pfad, auf dem der Prahler -JSON ausgeben wird

    • [Startupassembly] ist der relative Weg zur Start -up -Montage Ihrer Anwendung

    • [Swaggerdoc] ist der Name des Swagger -Dokuments, das Sie abrufen möchten, wie in Ihrer Startklasse konfiguriert

Verwenden des Tools mit dem .NET 6.0 SDK oder höher

  1. Erstellen Sie in Ihrem Projektstamm eine Toolmanifestdatei: 

    dotnet new tool-manifest

  2. Installieren Sie als lokales Werkzeug 

    dotnet tool install Swashbuckle.AspNetCore.Cli

  3. Stellen Sie sicher, dass das Tool richtig installiert wurde 

    dotnet swagger tofile --help

  4. Generieren Sie ein Dokument für Prahlerei / OpenAPI aus der Startbaugruppe Ihrer Anwendung 

    dotnet swagger tofile --output [output] [startupassembly] [swaggerdoc]

    Wo ...

    • [Ausgabe] ist der relative Pfad, auf dem der Prahler -JSON ausgeben wird

    • [Startupassembly] ist der relative Weg zur Start -up -Montage Ihrer Anwendung

    • [Swaggerdoc] ist der Name des Swagger -Dokuments, das Sie abrufen möchten, wie in Ihrer Startklasse konfiguriert

Verwenden Sie das CLI -Tool mit einer benutzerdefinierten Host -Konfiguration

Outs-of-the-Box wird das Tool im Kontext eines "Standard" -Webhosts ausgeführt. In einigen Fällen möchten Sie jedoch möglicherweise Ihre eigene Hostumgebung mitbringen, beispielsweise wenn Sie einen benutzerdefinierten DI -Container wie AutoFAC konfiguriert haben. Für dieses Szenario enthält das Swashbuckle CLI-Tool einen Kongresshaken für Ihre Anwendung.

Das heißt, wenn Ihre Bewerbung eine Klasse enthält, die einer der folgenden Namenskonventionen entspricht, wird diese Klasse verwendet, um einen Host für das CLI -Tool bereitzustellen.

  • public class SwaggerHostFactory , die eine öffentliche statische Methode namens CreateHost mit dem Rückkehrtyp IHost enthält

  • public class SwaggerWebHostFactory mit einer öffentlichen statischen Methode namens CreateWebHost mit Rückgabe Typ IWebHost

Beispielsweise könnte die folgende Klasse verwendet werden, um dieselbe Host -Konfiguration wie Ihre Anwendung zu nutzen:

 öffentliche Klasse Swaggerhostfactory {public static iOhos createHost () {return Program.CreateHostBuilder (neue String [0]). Build ();}}

Swashbuckle.aspnetcore.redoc

Änderung des relativen Weges zur Benutzeroberfläche

Standardmäßig wird die Redoc-Benutzeroberfläche bei "/api-docs" freigelegt. Bei Bedarf können Sie dies ändern, wenn Sie die Redoc Middleware aktivieren:

 app.USERREERDOC (C => {C.Routeprefix = "docs" ...}

Dokumenttitel ändern

Standardmäßig hat die Redoc -Benutzeroberfläche einen generischen Dokumenttitel. Sie können dies ändern, wenn Sie die Redoc Middleware aktivieren:

 app.USEERDOC (C => {C.DocumentTitle = "Meine API -Dokumente"; ...}

Anwenden Sie Redoc -Parameter an

Redoc wird mit eigenen Konfigurationsparametern ausgeliefert, die alle hier beschrieben https://github.com/rebilly/redoc/blob/main/readme.md#redoc-options-object. In Swashbuckle werden die meisten durch die Redoc Middleware -Optionen aufgetaucht:

 app.USERREERDOC (c => {C.Specurl ("/v1/Swagger.json"); C. enableUntrustedspec (); ("200.201"); SortPropSalphabetical ();});

Mit c.SpecUrl("/v1/swagger.json") addiert UseReDoc(...) nicht mehrere URLs.

CSS injizieren

Um das Erscheinungsbild zu optimieren, können Sie zusätzliche CSS -Stylesheets injizieren, indem Sie sie Ihrem wwwroot -Ordner hinzufügen und die relativen Pfade in den Middleware -Optionen angeben:

 app.USEERDOC (c => {... C.injectStylesheet ("/Redoc/Custom.css");}

Es ist auch möglich, das Thema mit der AdditionalItems Eigenschaft zu ändern, siehe https://github.com/rebilly/redoc/blob/main/readme.md#redoc-options-options-object für weitere Informationen.

 app.USEERDOC (c => {... configObject.additionalitems = ...}

Passen Sie index.html an

Um die Benutzeroberfläche über die oben aufgeführten Grundoptionen hinaus anzupassen, können Sie Ihre eigene Version der Seite Redoc index.html angeben:

 app.USERREERDOC (c => {C.Indexstream = () => GetType ().

Um loszulegen, sollten Sie Ihren benutzerdefinierten index.html auf der Standardversion stützen

Expandieren
Zusätzliche Informationen
Ähnliche Anwendungen
Empfohlen für Sie
Ähnliche Nachrichten Alle