NestJS Swagger API-Dokumentation

Einleitung

In der Welt der API-Entwicklung ist eine klare und umfassende Dokumentation entscheidend. Sie hilft nicht nur Entwicklern, zu verstehen, wie sie mit Ihrer API interagieren können, sondern dient auch als Vertrag zwischen Ihren Backend- und Frontend-Teams. NestJS, ein leistungsstarkes Node.js-Framework, integriert sich nahtlos mit Swagger, um eine schöne und interaktive API-Dokumentation zu generieren. In diesem Blogbeitrag werden wir Tipps und Tricks erkunden, um das Beste aus NestJS Swagger herauszuholen, einschließlich praktischer Beispiele zur Veranschaulichung jedes Punktes.

Swagger in Ihrem NestJS-Projekt einrichten

Zuerst müssen wir Swagger in Ihrer NestJS-Anwendung einrichten. Wenn Sie dies noch nicht getan haben, installieren Sie die notwendigen Pakete:

npm install --save @nestjs/swagger swagger-ui-express

Als nächstes können Sie Swagger in Ihrer Hauptanwendungsdatei konfigurieren:

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('Meine API')
    .setDescription('Die API-Beschreibung')
    .setVersion('1.0')
    .addTag('katzen')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

  await app.listen(3000);
}
bootstrap();
    

Dieses Setup macht Ihre API-Dokumentation unter http://localhost:3000/api zugänglich. Lassen Sie uns nun erkunden, wie wir diese Dokumentation weiter verbessern können.

Verwendung von Decorators zur Verbesserung Ihrer Endpunkte

Eine der leistungsstärksten Funktionen von NestJS Swagger ist die Möglichkeit, Decorators zu verwenden, um Ihre API-Endpunkte zu bereichern. Diese Decorators helfen Ihnen, die Metadaten zu definieren, die Swagger zur Generierung der Dokumentation verwendet.

Betrachten wir zum Beispiel den folgenden Controller:

import { Controller, Get, Post, Body, Param } from '@nestjs/common';
import { ApiTags, ApiResponse, ApiParam, ApiBody } from '@nestjs/swagger';

class CreateCatDto {
  name: string;
  age: number;
}

@ApiTags('katzen')
@Controller('katzen')
export class CatsController {
  private cats = [];

  @Post()
  @ApiBody({ type: CreateCatDto })
  @ApiResponse({ status: 201, description: 'Katze erfolgreich erstellt' })
  createCat(@Body() createCatDto: CreateCatDto) {
    this.cats.push(createCatDto);
    return { message: `Katze ${createCatDto.name} hinzugefügt!` };
  }

  @Get(':id')
  @ApiResponse({ status: 200, description: 'Der gefundene Datensatz' })
  @ApiResponse({ status: 404, description: 'Katze nicht gefunden' })
  @ApiParam({ name: 'id', required: true, description: 'Katzen-ID' })
  getCat(@Param('id') id: string) {
    const cat = this.cats.find(c => c.name === id);
    if (!cat) {
      throw new NotFoundException(`Katze mit ID ${id} nicht gefunden`);
    }
    return cat;
  }
}
    

In diesem Beispiel:

• @ApiTags kategorisiert die Endpunkte in der Dokumentation und erleichtert so die Navigation für die Benutzer.
• @ApiResponse liefert Informationen über die möglichen HTTP-Antworten und verbessert die Klarheit Ihrer API.
• @ApiParam beschreibt die akzeptierten Parameter des Endpunkts.
• @ApiBody gibt die erwartete Struktur des Anfragekörpers unter Verwendung eines Datenübertragungsobjekts (DTO) an.

Dokumentation von Anfragekörpern und Abfrageparametern

Um Ihre API benutzerfreundlicher zu gestalten, ist es wichtig, Anfragekörper und Abfrageparameter zu dokumentieren. Verwenden Sie die Decorators @ApiBody und @ApiQuery, um dies zu erreichen:

import { Controller, Post, Body, Query } from '@nestjs/common';
import { ApiBody, ApiQuery } from '@nestjs/swagger';

class CreateCatDto {
  name: string;
  age: number;
}

@Controller('katzen')
export class CatsController {
  private cats = [];

  @Post()
  @ApiBody({ type: CreateCatDto })
  createCat(@Body() createCatDto: CreateCatDto) {
    this.cats.push(createCatDto);
    return `Katze ${createCatDto.name} hinzugefügt!`;
  }

  @Get()
  @ApiQuery({ name: 'age', required: false, description: 'Katzen nach Alter filtern' })
  findCats(@Query('age') age: number) {
    return age
      ? this.cats.filter(cat => cat.age === age)
      : this.cats;
  }
}
    

In diesem Beispiel:

• @ApiBody gibt die erwartete Struktur des Anfragekörpers unter Verwendung eines Datenübertragungsobjekts (DTO) an.
• @ApiQuery dokumentiert die Abfrageparameter und verbessert die Benutzerfreundlichkeit der API.

Testen von API-Anfragen über die Swagger UI

Ein großer Vorteil der Verwendung von Swagger UI ist die Möglichkeit, Ihre API-Endpunkte direkt über die Oberfläche zu testen. Hier erfahren Sie, wie Sie dies tun können:

Sending a POST-Anfrage

1. Navigieren Sie zur Swagger UI unter http://localhost:3000/api.

2. Suchen Sie den Endpunkt Katze erstellen unter dem Tag katzen.

3. Klicken Sie auf den Endpunkt und dann auf Try it out.

4. Geben Sie den folgenden JSON im Anfragekörper ein:

{
  "name": "Fluffy",
  "age": 3
}
    

5. Klicken Sie auf Execute, um die Anfrage zu senden. Sie sollten eine Antwort erhalten, die angibt, dass die Katze erfolgreich hinzugefügt wurde.

Sending a GET-Anfrage

1. Suchen Sie unter derselben Swagger UI den Endpunkt Katze abrufen.

2. Klicken Sie auf den Endpunkt und dann auf Try it out.

3. Geben Sie den Namen der Katze (z.B. Fluffy) in das Parameterfeld ein.

4. Klicken Sie auf Execute, um die Informationen über die Katze abzurufen. Wenn die Katze existiert, sollten Sie die Details der Katze in der Antwort sehen.

5. Wenn Sie einen Namen eingeben, der nicht existiert, erhalten Sie eine 404-Fehlermeldung, die anzeigt, dass die Katze nicht gefunden wurde.

Gruppierung von Endpunkten mit Tags

Die Organisation Ihrer API-Endpunkte in logische Gruppen macht die Dokumentation einfacher zu navigieren. Sie können Tags verwenden, um Endpunkte zu kategorisieren. Zum Beispiel:

@ApiTags('katzen')
@Controller('katzen')
export class CatsController {
  // ...
}
    

Die Verwendung von Tags verbessert die Benutzererfahrung erheblich, indem sie eine klare Struktur bietet.

Zusammenfassung

Eine effektive API-Dokumentation ist entscheidend für jede erfolgreiche Anwendung. Durch die Nutzung der Integration von NestJS mit Swagger können Sie klare, umfassende und interaktive API-Dokumentationen erstellen, die sowohl Ihrem Team als auch externen Entwicklern zugutekommen.

Die in diesem Beitrag beschriebenen Tipps und Tricks – von der Einrichtung von Swagger bis zur Anpassung der UI – helfen Ihnen, das Potenzial der Dokumentation Ihrer API zu maximieren. Denken Sie daran, dass eine gut dokumentierte API eine glückliche API ist!