Swagger ist ein kostenloses Open-Source-Framework zum Erstellen einer interaktiven und benutzerfreundlichen API-Dokumentation. Es generiert interaktive Webseiten, mit denen Sie eine API mit verschiedenen Eingaben testen können.
Swagger unterstützt sowohl JSON- als auch XML-Payloads. Die generierte Dokumentation ist für Entwickler und Nicht-Entwickler geeignet.
Sie können Ihre NestJS-Web-APIs über Swagger mit einfachen Decorators dokumentieren, ohne Ihre IDE verlassen zu müssen.
Schritt 1: Generieren der API
Bevor Sie beginnen, müssen Sie eine Demo-API erstellen, deren Dokumentation Swagger generiert.
Sie generieren die Demo-API mithilfe der NestJS-CLI von Grund auf neu.
Generieren Sie zunächst ein neues NestJS-Projekt, indem Sie Folgendes ausführen:
Nest neu <Name-Ihres-Projekts>
Ändern Sie dann das Verzeichnis in Ihr bereits erstelltes Projekt, indem Sie Folgendes ausführen:
CD <Name-Ihres-Projekts>
Als Nächstes generieren Sie eine REST-API mit der CLI, indem Sie Folgendes ausführen:
Nest-Generate-Ressourcen-Demo --keine spez
Sie sehen eine Abfrage mit der Frage „Welche Transportschicht verwenden Sie?“ auswählen REST-API.
Sie sehen eine weitere Abfrage mit der Frage: „Möchten Sie CRUD-Einstiegspunkte generieren?“ Typ Y und schlagen Eintreten.
Der obige Befehl generiert eine voll funktionsfähige REST-API mit CRUD-Endpunkten und ohne die Unit-Test-Dateien. Daher die --keine spez Flag im obigen Befehl.
Schritt 2: Installieren Sie Swagger
Installieren Sie Swagger und seine Express-UI-Bibliothek, indem Sie Folgendes ausführen:
npm Installieren--save @nestjs/swagger swagger-ui-express
Schritt 3: Swagger konfigurieren
In deiner main.ts Datei, importieren SwaggerModul und DocumentBuilder aus @nestjs/swagger.
DocumentBuilder hilft bei der Strukturierung eines Basisdokuments. Es bietet mehrere Methoden, die Sie miteinander verketten und mit der schließen können bauen Methode.
Diese Methoden ermöglichen die Konfiguration vieler Attribute wie Titel, Beschreibung und Version.
Ein... kreieren Konfig Objektvariable in Ihrer Bootstrap funktionieren so:
konst config = Neu DocumentBuilder()
.setTitle('Demo-API')
.setDescription('Eine Demo-API mit CRUD-Funktionalität')
.setVersion('1.0')
.bauen();
Eine neue Instanz von DocumentBuilder erstellt ein Basisdokument, das mit dem übereinstimmt OpenAPI-Spezifikation. Sie können diese Instanz dann verwenden, um den Titel, die Beschreibung und die Version über die entsprechenden Methoden festzulegen.
Als Nächstes müssen Sie ein vollständiges Dokument mit allen HTTP-Routen erstellen, die mithilfe des Basisdokuments definiert wurden.
Rufen Sie dazu die an Dokument erstellen Methode auf SwaggerModule. createDocument akzeptiert zwei Argumente: eine Anwendungsinstanz und ein Swagger-Optionsobjekt. Speichern Sie das Ergebnis dieses Aufrufs in einer Variablen zur späteren Verwendung:
konstdokumentieren = SwaggerModule.createDocument (App, Konfiguration);
Als nächstes rufen Sie an Konfiguration Methode auf SwaggerModule. Die Setup-Methode akzeptiert drei Argumente:
- Der Swagger-UI-Pfad. Per Konvention können Sie „api“ verwenden.
- Eine Anwendungsinstanz
- Das vollständige Dokument
Darüber hinaus akzeptiert die Setup-Methode ein optionales Optionsobjekt. Sehen Dokumentation von NestJS zu Swagger-Dokumentoptionen um mehr darüber zu erfahren.
So:
SwaggerModule.setup('API', App, Dokument);
Starten Sie Ihre Anwendung und gehen Sie zu http://localhost:
Sie sollten die Swagger-Benutzeroberfläche auf der Seite angezeigt sehen.
Das obige Bild ist die Standardansicht der Swagger-Benutzeroberfläche, in der alle HTTP-Routen in Ihrem Controller definiert sind. Sie müssen es an Ihre API-Funktionalität anpassen.
Schritt 4: API-Eigenschaften anpassen
Standardmäßig stellt Swagger dem gesamten Abschnitt der HTTP-Route eine Überschrift mit dem Präfix „default“ voran. Sie können dies ändern, indem Sie Ihre Controller-Klasse mit kommentieren @ApiTags decorator und übergeben Sie Ihr bevorzugtes Tag als Argument.
So:
// demo.controller.ts
importieren { ApiTags } aus '@nestjs/swagger';
@ApiTags('Demo')
@Regler('Demo')
ExportKlasse DemoController {
Der Abschnitt Schemas enthält die Datenübertragungsobjekte in Ihrer API. Derzeit enthält die Benutzeroberfläche keine ihrer Eigenschaften.
Um ihre Eigenschaften in der Benutzeroberfläche zu deklarieren, fügen Sie einfach Decorators hinzu. Beschriften Sie jede erforderliche Eigenschaft mit dem @ApiProperty Dekorateur. Kommentieren Sie optionale Eigenschaften mit dem @ApiPropertyOptional Dekorateur.
Zum Beispiel:
// create-demo.dto.ts
importieren { ApiProperty, ApiPropertyOptional } aus '@nestjs/swagger';
ExportKlasse CreateDemoDto {
@ApiProperty({
Typ: Schnur,
Beschreibung: 'Dies ist eine erforderliche Eigenschaft',
})
Eigentum: Schnur;
@ApiPropertyOptional({
Typ: Schnur,
Beschreibung: 'Dies ist eine optionale Eigenschaft',
})
optionale Eigenschaft: Schnur;
}
Die Dekoratoren @ApiProperty und @ApiPropertyOptional akzeptieren jeweils ein Optionsobjekt. Dieses Objekt beschreibt die Eigenschaft, die unten folgt.
Beachten Sie, dass das options-Objekt JavaScript und nicht TypeScript verwendet. Daher die JavaScript-Typdeklarationen (dh String, nicht String).
Durch Kommentieren der Eigenschaften des Datenübertragungsobjekts wird ein Beispiel der erwarteten Daten zum Abschnitt „Schemas“ hinzugefügt. Es aktualisiert auch die zugehörige HTTP-Route mit einem Beispiel der erwarteten Daten.
Schritt 5: API-Antworten festlegen
Verwenden Sie in Ihrer Controller-Klasse die @ApiResponse Dekorateure, um alle möglichen Antworten für jede HTTP-Route zu dokumentieren. Für jeden Endpunkt beschreiben die verschiedenen @ApiResponse-Decorators die Art der zu erwartenden Antworten.
Wir haben erklärt allgemeine HTTP-Antworten, falls Sie nicht wissen, was sie bedeuten.
Die @ApiResponse-Dekoratoren akzeptieren ein optionales Objekt, das die Antwort beschreibt.
Häufige POST-Antworten
Bei einer POST-Anfrage sind die wahrscheinlichen Antworten:
- APICreatedResponse, für erfolgreiche 201 erstellte Antworten.
- ApiUnprocessableEnityResponse, für fehlgeschlagene 422 nicht verarbeitbare Entitätsantworten.
- APIForbiddenResponse, für 403 verbotene Antworten.
Zum Beispiel:
// demo.controller.ts
@Post()
@ApiCreatedResponse({ Beschreibung: 'Erfolgreich erstellt' })
@ApiUnprocessableEntityResponse({ Beschreibung: 'Bad Request' })
@ApiForbiddenAntwort({ Beschreibung: 'Unautorisierte Anfrage' })
schaffen(@Körper() createDemoDto: CreateDemoDto) {
RückkehrDies.demoService.create (createDemoDto);
}
Allgemeine GET-Antworten
Bei GET-Anforderungen sind die wahrscheinlichen Antworten:
- ApiOkResponse, für 200 OK-Antworten.
- APIForbiddenResponse, für 403 verbotene Antworten.
- ApiNotFoundResponse, für 404 nicht gefundene Antworten.
Zum Beispiel:
// demo.controller.ts
@Erhalten()
@ApiOkAntwort({ description: 'Die Ressourcen wurden erfolgreich zurückgegeben' })
@ApiForbiddenAntwort({ Beschreibung: 'Unautorisierte Anfrage' })
finde alle() {
RückkehrDies.demoService.findAll();
}
@Erhalten(':Ich würde')
@ApiOkAntwort({ Beschreibung: 'Die Ressource wurde erfolgreich zurückgegeben' })
@ApiForbiddenAntwort({ Beschreibung: 'Unautorisierte Anfrage' })
@ApiNotFoundResponse({ Beschreibung: 'Ressource nicht gefunden' })
einen finden(@Param('Ich tat: Schnur) {
RückkehrDies.demoService.findOne(+id);
}
Allgemeine PATCH- und UPDATE-Antworten
Bei PATCH- und UPDATE-Anforderungen sind die wahrscheinlichen Antworten:
- ApiOkResponse, für 200 OK-Antworten.
- ApiNotFoundResponse, für 404 nicht gefundene Antworten.
- ApiUnprocessibleEntityResponse, für fehlgeschlagene 422 nicht verarbeitbare Entitätsantworten.
- APIForbiddenResponse, für 403 verbotene Antworten.
Zum Beispiel:
// demo.controller.ts
@Patch(':Ich würde')
@ApiOkAntwort({ Beschreibung: 'Die Ressource wurde erfolgreich aktualisiert' })
@ApiNotFoundResponse({ Beschreibung: 'Ressource nicht gefunden' })
@ApiForbiddenAntwort({ Beschreibung: 'Unautorisierte Anfrage' })
@ApiUnprocessableEntityResponse({ Beschreibung: 'Bad Request' })
aktualisieren(@Param('Ich tat: Schnur, @Körper() updateDemoDto: UpdateDemoDto) {
RückkehrDies.demoService.update(+id, updateDemoDto);
}
Häufige DELETE-Antworten
Bei DELETE-Anforderungen sind die wahrscheinlichen Antworten:
- ApiOkResponse, für 200 OK-Antworten.
- APIForbiddenResponse, für 403 verbotene Antworten.
- ApiNotFoundResponse, für 404 nicht gefundene Antworten.
Zum Beispiel:
// demo.controller.ts
@Löschen(':Ich würde')
@ApiOkAntwort({ Beschreibung: 'Die Ressource wurde erfolgreich zurückgegeben' })
@ApiForbiddenAntwort({ Beschreibung: 'Unautorisierte Anfrage' })
@ApiNotFoundResponse({ Beschreibung: 'Ressource nicht gefunden' })
Löschen(@Param('Ich tat: Schnur) {
RückkehrDies.demoService.remove(+id);
}
Diese Dekorateure füllen Ihre Dokumentation mit möglichen Antworten. Sie können sie mithilfe des Dropdown-Menüs neben jeder Route anzeigen.
Anzeigen Ihrer Dokumentation
Wenn Ihre Einrichtung abgeschlossen ist, können Sie Ihre Dokumentation unter anzeigen lokaler Host:
Die wesentlichen Bestandteile der Swagger-API-Dokumentation sind die Beschreibung, die Antworttypen und die Schemadefinition. Dies sind die grundlegenden Dinge, die zum Erstellen einer guten API-Dokumentation erforderlich sind.
