DANGER
Le module Swagger est actuellement en version Alpha, de nombreuses fonctionnalités sont manquantes. Si quelque chose dont vous avez besoin n'est pas encore ici, veuillez remplir une demande de problème ou de fonctionnalité.
Corps, Query et Params
Le module Swagger
recherche tous les décorateurs @Body()
et @Query()
dans les gestionnaires de route pour générer le document API. Il crée également des définitions de modèle correspondantes en profitant de la réflexion. Considérons le code suivant :
@Post()
async create(@Body() createTodoDto: CreateTodoDto) {
this.todoService.create(createTodoDto);
}
TIP
Pour définir explicitement la définition de corps, utilisez le décorateur @BodyType(Todo)
. Pour définir explicitement la définition de la requête, utilisez le décorateur @QueryType(Todo)
.
Sur la base de Todo
, la définition de modèle suivante sera créée dans Swagger UI :
Afin de rendre les propriétés de la classe visibles dans le module Swagger
, nous devons les annoter avec le décorateur @ApiProperty()
:
export class CreateTodoDto {
@ApiProperty()
name!: string;
@ApiProperty()
priority!: number;
@ApiProperty()
colorLabel!: string;
}
TIP
Si l'une de ces propriétés est facultative, vous pouvez utiliser le décorateur @Optional()
.
Ouvrons le navigateur et vérifions le modèle Todo
généré :
Type de retour
En raison de l'absence de métadonnées design:return
dans SWC (le compilateur TypeScript de Deno), vous devez obligatoirement utiliser le décorateur @ReturnedType
pour indiquer ce que votre point d'extrémité renverra :
@ReturnedType(Todo)
@Get(':id')
async getById(@Param('id') id: string): Todo {
return this.todoService.getById(id);
}
Si votre route renvoie un tableau, passez true
en tant que deuxième argument de ReturnedType
:
@ReturnedType(Todo, true)
@Get()
async getTodos(): Todo[] {
return this.todoService.getAll();
}
Enumérations
Pour identifier une enum
, nous devons définir manuellement la propriété enum
sur @ApiProperty
avec un tableau de valeurs.
@ApiProperty({ enum: ['Admin', 'Moderator', 'User']})
role: UserRole;