Merge pull request #7 from fga-eps-mds/feat#95/conf-swagger

[FEAT] Adiciona Swagger à API (fga-eps-mds/2024.2-ARANDU-DOC#95)

.env.dev.template

@@ -8,4 +8,5 @@ ME_CONFIG_BASICAUTH=
 ME_CONFIG_BASICAUTH_USERNAME=
 ME_CONFIG_BASICAUTH_PASSWORD=
 USER_SERVICE_URL=
-AUTH_SERVICE_URL=
+AUTH_SERVICE_URL=
+NODE_ENV=development

.env.prod.template

@@ -8,4 +8,5 @@ ME_CONFIG_BASICAUTH=
 ME_CONFIG_BASICAUTH_USERNAME=
 ME_CONFIG_BASICAUTH_PASSWORD=
 USER_SERVICE_URL=
-AUTH_SERVICE_URL=
+AUTH_SERVICE_URL=
+NODE_ENV=production

package.json

@@ -27,6 +27,7 @@
     "@nestjs/core": "^10.0.0",
     "@nestjs/mongoose": "^10.0.10",
     "@nestjs/platform-express": "^10.0.0",
+    "@nestjs/swagger": "^8.1.0",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.14.1",
     "dotenv": "^16.4.5",

src/content/content.controller.ts

@@ -1,23 +1,30 @@
 import {
+  Body,
   Controller,
-  Post,
-  Get,
-  Patch,
   Delete,
-  Param,
-  Body,
-  NotFoundException,
+  Get,
   Logger,
+  NotFoundException,
+  Param,
+  Patch,
+  Post,
 } from '@nestjs/common';
-import { ContentService } from './content.service';
+import { ApiBody } from '@nestjs/swagger';
 import { Content } from './content.schema';
+import { ContentService } from './content.service';
+import { CreateContentDto } from './dtos/create-content.dto';
 import { UpdateContentsOrderDto } from './dtos/update-content-order.dto';
+import { UpdateContentDto } from './dtos/update-content.dto';
 
 @Controller('contents')
 export class ContentController {
   private readonly logger = new Logger(ContentController.name);
   constructor(private readonly contentService: ContentService) {}
 
+  @ApiBody({
+    type: CreateContentDto,
+    description: 'Estrutura para criação de conteúdo',
+  })
   @Post()
   async createContent(
     @Body() body: { title: string; content: string; trailId: string },
@@ -46,6 +53,10 @@ export class ContentController {
     return this.contentService.findContentsByTrailId(id);
   }
 
+  @ApiBody({
+    type: UpdateContentDto,
+    description: 'Estrutura para edição de conteúdo',
+  })
   @Patch(':id')
   async updateContent(
     @Param('id') id: string,
@@ -59,6 +70,10 @@ export class ContentController {
     return this.contentService.deleteContent(id);
   }
 
+  @ApiBody({
+    type: UpdateContentsOrderDto,
+    description: 'Estrutura para edição da ordem do conteúdo',
+  })
   @Patch('order/update-order')
   async updateTrailOrder(@Body() contentsDto: UpdateContentsOrderDto) {
     this.logger.log(

src/content/content.service.ts

@@ -1,9 +1,9 @@
 import { Injectable, Logger, NotFoundException } from '@nestjs/common';
 import { InjectModel } from '@nestjs/mongoose';
 import { Model, Types } from 'mongoose';
-import { Content } from './content.schema';
 import { Trail } from '../trail/trail.schema';
 import { TrailService } from '../trail/trail.service';
+import { Content } from './content.schema';
 import { ContentInterface } from './dtos/update-content-order.dto';
 
 @Injectable()

src/content/dtos/create-content.dto.ts

@@ -1,15 +1,28 @@
-import { IsString, IsNotEmpty, IsMongoId } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+import { IsMongoId, IsNotEmpty, IsString } from 'class-validator';
 
 export class CreateContentDto {
+  @ApiProperty({
+    example: 'Título',
+    required: true
+  })
   @IsString()
   @IsNotEmpty()
   title: string;
 
+  @ApiProperty({
+    example: 'Conteúdo',
+    required: true
+  })
   @IsString()
   @IsNotEmpty()
   content: string;
 
+  @ApiProperty({
+    example: 'id-da-trilha',
+    required: true
+  })
   @IsMongoId()
   @IsNotEmpty()
-  trail: string;
+  trailId: string;
 }

src/content/dtos/update-content.dto.ts

@@ -0,0 +1,28 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsMongoId, IsOptional, IsString } from 'class-validator';
+
+export class UpdateContentDto {
+  @ApiProperty({
+    example: 'Título',
+    required: false
+  })
+  @IsString()
+  @IsOptional()
+  title?: string;
+
+  @ApiProperty({
+    example: 'Conteúdo',
+    required: false
+  })
+  @IsString()
+  @IsOptional()
+  content?: string;
+
+  @ApiProperty({
+    example: 'id-da-trilha',
+    required: false
+  })
+  @IsMongoId()
+  @IsOptional()
+  trailId?: string;
+}

src/journey/dtos/create-journey.dto.ts

@@ -1,13 +1,26 @@
-import { IsString, IsOptional, IsMongoId } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+import { IsMongoId, IsOptional, IsString } from 'class-validator';
 
 export class CreateJourneyDto {
+  @ApiProperty({
+    example: 'Título',
+    required: true
+  })
   @IsString()
   title: string;
 
+  @ApiProperty({
+    example: 'Descrição',
+    required: false
+  })
   @IsOptional()
   @IsString()
   description: string;
 
+  @ApiProperty({
+    example: 'id-do-start-point',
+    required: false
+  })
   @IsOptional()
   @IsMongoId()
   pointId?: string;

src/journey/dtos/manageJourneyTrail.dto.ts

@@ -0,0 +1,12 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsMongoId, IsNotEmpty } from 'class-validator';
+
+export class ManageJourneyTrailDTO {
+  @ApiProperty({
+    example: 'id-da-trilha',
+    required: true
+  })
+  @IsMongoId()
+  @IsNotEmpty()
+  trailId: string;
+}

src/journey/journey.controller.ts

@@ -1,24 +1,30 @@
 import {
+  Body,
   Controller,
+  Delete,
   Get,
-  Post,
-  Body,
+  Logger,
+  NotFoundException,
   Param,
-  Put,
-  Delete,
   Patch,
-  NotFoundException,
-  Logger,
+  Post,
+  Put,
 } from '@nestjs/common';
-import { JourneyService } from './journey.service';
+import { ApiBody } from '@nestjs/swagger';
 import { CreateJourneyDto } from './dtos/create-journey.dto';
+import { ManageJourneyTrailDTO } from './dtos/manageJourneyTrail.dto';
 import { UpdateJourneysOrderDto } from './dtos/updateJourneyOrder';
+import { JourneyService } from './journey.service';
 
 @Controller('journeys')
 export class JourneyController {
   private readonly logger = new Logger(JourneyController.name);
   constructor(private readonly journeyService: JourneyService) {}
 
+  @ApiBody({
+    type: CreateJourneyDto,
+    description: 'Estrutura para criação de jornadas',
+  })
   @Post()
   async create(@Body() body: CreateJourneyDto) {
     const pointId = body.pointId;
@@ -44,6 +50,10 @@ export class JourneyController {
     return this.journeyService.findById(id);
   }
 
+  @ApiBody({
+    type: CreateJourneyDto,
+    description: 'Estrutura para edição de jornadas',
+  })
   @Put(':id')
   async update(
     @Param('id') id: string,
@@ -57,14 +67,20 @@ export class JourneyController {
     return this.journeyService.delete(id);
   }
 
+  @ApiBody({
+    type: ManageJourneyTrailDTO
+  })
   @Patch(':id/add-trail')
   async addTrailToJourney(
     @Param('id') id: string,
-    @Body() body: { trailId: string },
+    @Body() body: ManageJourneyTrailDTO,
   ) {
     return this.journeyService.addTrailToJourney(id, body.trailId);
   }
 
+  @ApiBody({
+    type: UpdateJourneysOrderDto
+  })
   @Patch('update-journeys-order')
   async updateTrailOrder(@Body() journeysDto: UpdateJourneysOrderDto) {
     this.logger.log(

src/main.ts

@@ -1,13 +1,27 @@
 import { Logger, ValidationPipe } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 import { NestFactory } from '@nestjs/core';
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
 import { AppModule } from './app.module';
 
 const configService = new ConfigService();
 const logger = new Logger('Main');
 
 async function bootstrap() {
   const app = await NestFactory.create(AppModule);
+
+  logger.log(`Application runnning at ${configService.get('NODE_ENV')}`);
+  if ( configService.get('NODE_ENV') !== 'production' ) {
+    const config = new DocumentBuilder()
+      .setTitle('ARANDU')
+      .setDescription('Endpoints do StudioMaker ARANDU')
+      .setVersion('1.0')
+      .addTag('StudioMaker')
+      .build();
+    const documentFactory = () => SwaggerModule.createDocument(app, config);
+    SwaggerModule.setup('api', app, documentFactory);
+  }
+
   app.useGlobalPipes(new ValidationPipe());
   app.enableCors();
   await app.listen(configService.get('PORT'), '0.0.0.0', () => {

src/start_point/dtos/create-start-point.dto.ts

@@ -1,15 +1,32 @@
-import { IsString, IsOptional, IsMongoId } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+import { IsMongoId, IsOptional, IsString } from 'class-validator';
 
 export class CreateStartPointDto {
+  @ApiProperty({
+    example: 'Nome',
+    required: true
+  })
   @IsString()
   name: string;
 
+  @ApiProperty({
+    example: 'Descrição',
+    required: true
+  })
   @IsString()
   description: string;
 
+  @ApiProperty({
+    example: 'id-do-user',
+    required: false
+  })
   @IsOptional()
   @IsMongoId()
   user?: string;
 
+  @ApiProperty({
+    example: '1',
+    required: false
+  })
   order?: Number;
 }

src/start_point/dtos/manageStartPointJourney.dto.ts

@@ -0,0 +1,12 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsMongoId, IsNotEmpty } from 'class-validator';
+
+export class ManageStartPointJourneyDTO {
+  @ApiProperty({
+    example: 'id-da-jornada',
+    required: true
+  })
+  @IsMongoId()
+  @IsNotEmpty()
+  journeyId: string;
+}