feat: add initial swagger docs

asalmada · Jul 12, 2023 · d97b83a · d97b83a
1 parent a0455c4
commit d97b83a
Show file tree

Hide file tree

Showing 13 changed files with 275 additions and 157 deletions.
diff --git a/package.json b/package.json
@@ -24,6 +24,7 @@
     "@nestjs/core": "^10.0.0",
     "@nestjs/mongoose": "^10.0.0",
     "@nestjs/platform-express": "^10.0.0",
+    "@nestjs/swagger": "7.1.1",
     "csv-parse": "5.4.0",
     "mongoose": "^7.3.1",
     "reflect-metadata": "^0.1.13",

diff --git a/src/app.controller.spec.ts b/src/app.controller.spec.ts
diff --git a/src/app.controller.ts b/src/app.controller.ts
diff --git a/src/app.module.ts b/src/app.module.ts
@@ -4,9 +4,6 @@ import { MongooseModule } from '@nestjs/mongoose';
 
 import { FishesModule } from './fishes/fishes.module';
 
-import { AppController } from './app.controller';
-import { AppService } from './app.service';
-
 @Module({
   imports: [
     ConfigModule.forRoot(),
@@ -16,7 +13,7 @@ import { AppService } from './app.service';
     ),
     FishesModule,
   ],
-  controllers: [AppController],
-  providers: [AppService],
+  controllers: [],
+  providers: [],
 })
 export class AppModule {}
diff --git a/src/app.service.ts b/src/app.service.ts
diff --git a/src/fishes/dto/fish.dto.ts b/src/fishes/dto/fish.dto.ts
@@ -0,0 +1,97 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IFishLocation } from '../interfaces/fish.interface';
+
+const monthProperty = {
+  oneOf: [
+    {
+      type: 'array',
+      items: {
+        type: 'string',
+        enum: [
+          'All day',
+          '9 AM - 4 PM',
+          '4 PM - 9 AM',
+          '9 PM - 4 AM',
+          '4 AM - 9 PM',
+        ],
+      },
+    },
+    { type: 'undefined' },
+  ],
+};
+const availabilityProperties = {
+  january: monthProperty,
+  february: monthProperty,
+  march: monthProperty,
+  april: monthProperty,
+  may: monthProperty,
+  june: monthProperty,
+  july: monthProperty,
+  august: monthProperty,
+  september: monthProperty,
+  october: monthProperty,
+  november: monthProperty,
+  december: monthProperty,
+};
+
+class Availability {
+  @ApiProperty({
+    type: 'object',
+    properties: availabilityProperties,
+  })
+  northern_hemisphere: Object;
+
+  @ApiProperty({
+    type: 'object',
+    properties: availabilityProperties,
+  })
+  southern_hemisphere: Object;
+}
+
+export class FishDto {
+  @ApiProperty()
+  name: string;
+
+  @ApiProperty()
+  icon_image: string;
+
+  @ApiProperty()
+  critterpedia_image: string;
+
+  @ApiProperty()
+  furniture_image: string;
+
+  @ApiProperty()
+  minimum_catches_to_spawn: number;
+
+  @ApiProperty()
+  sale_price: number;
+
+  @ApiProperty()
+  spawn_frequency: string;
+
+  @ApiProperty({
+    enum: [
+      'River',
+      'Pond',
+      'River (clifftop)',
+      'River (mouth)',
+      'Sea',
+      'Pier',
+      'Sea (rainy days)',
+    ],
+  })
+  location: IFishLocation;
+
+  @ApiProperty()
+  shadow_size: string;
+
+  @ApiProperty()
+  blathers_description: string;
+
+  @ApiProperty()
+  catch_phrase: string;
+
+  @ApiProperty()
+  availability: Availability;
+}
diff --git a/src/fishes/fishes.controller.ts b/src/fishes/fishes.controller.ts
@@ -6,68 +6,107 @@ import {
   HttpException,
   HttpStatus,
 } from '@nestjs/common';
+import {
+  ApiOperation,
+  ApiTags,
+  ApiOkResponse,
+  ApiQuery,
+  ApiBadRequestResponse,
+} from '@nestjs/swagger';
 
 import { FishesService } from './fishes.service';
-import { Fish, IMonth } from './schemas/fish.schema';
-import { IQueryParams } from './interfaces/fish.interface';
 
+import { Fish } from './schemas/fish.schema';
+import { IQueryParams, IMonth } from './interfaces/fish.interface';
+import { FishDto } from './dto/fish.dto';
+
+const hemispheres = ['northern_hemisphere', 'southern_hemisphere'];
+const months = [
+  'january',
+  'february',
+  'march',
+  'april',
+  'may',
+  'june',
+  'july',
+  'august',
+  'september',
+  'october',
+  'november',
+  'december',
+];
+const times = [
+  '12 AM',
+  '1 AM',
+  '2 AM',
+  '3 AM',
+  '4 AM',
+  '5 AM',
+  '6 AM',
+  '7 AM',
+  '8 AM',
+  '9 AM',
+  '10 AM',
+  '11 AM',
+  '12 PM',
+  '1 PM',
+  '2 PM',
+  '3 PM',
+  '4 PM',
+  '5 PM',
+  '6 PM',
+  '7 PM',
+  '8 PM',
+  '9 PM',
+  '10 PM',
+  '11 PM',
+];
+
+@ApiTags('Fishes')
 @Controller('fishes')
 export class FishesController {
   constructor(private fishesService: FishesService) {}
 
   // Query params verifiers
   private isOfTypeIMonth(month: string): month is IMonth {
-    return [
-      'january',
-      'february',
-      'march',
-      'april',
-      'may',
-      'june',
-      'july',
-      'august',
-      'september',
-      'october',
-      'november',
-      'december',
-    ].includes(month);
+    return months.includes(month);
   }
 
   private isValidHemisphere(hemisphere: string): boolean {
-    return ['northern_hemisphere', 'southern_hemisphere'].includes(hemisphere);
+    return hemispheres.includes(hemisphere);
   }
 
   private isValidTime(time: string): boolean {
-    return [
-      '12 AM',
-      '1 AM',
-      '2 AM',
-      '3 AM',
-      '4 AM',
-      '5 AM',
-      '6 AM',
-      '7 AM',
-      '8 AM',
-      '9 AM',
-      '10 AM',
-      '11 AM',
-      '12 PM',
-      '1 PM',
-      '2 PM',
-      '3 PM',
-      '4 PM',
-      '5 PM',
-      '6 PM',
-      '7 PM',
-      '8 PM',
-      '9 PM',
-      '10 PM',
-      '11 PM',
-    ].includes(time);
+    return times.includes(time);
   }
 
   // Routes
   @Get()
+  @ApiOperation({ summary: 'Obtain all fishes' })
+  @ApiQuery({
+    name: 'hemisphere',
+    enum: hemispheres,
+    required: false,
+  })
+  @ApiQuery({
+    name: 'month',
+    enum: months,
+    required: false,
+  })
+  @ApiQuery({
+    name: 'time',
+    enum: times,
+    required: false,
+  })
+  @ApiOkResponse({
+    description: 'The fishes were returned successfully',
+    type: FishDto,
+    isArray: true,
+  })
+  @ApiBadRequestResponse({
+    description:
+      'Invalid query param informed or searching active hours without informing a month',
+  })
   public getFishes(@Query() query: IQueryParams): Promise<Fish[]> {
     if (query.month && !this.isOfTypeIMonth(query.month))
       throw new HttpException(
@@ -97,6 +136,11 @@ export class FishesController {
   }
 
   @Get(':name')
+  @ApiOkResponse({
+    description: 'The found fish record, or null, if not found',
+    type: FishDto,
+  })
+  @ApiOperation({ summary: 'Obtain all information from a specific fish' })
   public getFish(@Param('name') name: string): Promise<Fish | null> {
     return this.fishesService.findOne(name);
   }

diff --git a/src/fishes/fishes.service.ts b/src/fishes/fishes.service.ts
@@ -49,6 +49,8 @@ export class FishesService {
 
   public find(queryParams: IQueryParams): Promise<Fish[]> {
     const buildQuery = () => {
+      if (!queryParams.month) return {};
+
       // If request informed a desired hour, we must obtain all possible active hours that contemplates it
       let formattedTime;
       if (queryParams.time) formattedTime = this.formatTime(queryParams.time);

diff --git a/src/fishes/interfaces/fish.interface.ts b/src/fishes/interfaces/fish.interface.ts
@@ -1,3 +1,36 @@
+export type IMonth =
+  | 'january'
+  | 'february'
+  | 'march'
+  | 'april'
+  | 'may'
+  | 'june'
+  | 'july'
+  | 'august'
+  | 'september'
+  | 'october'
+  | 'november'
+  | 'december';
+
+export type IFishLocation =
+  | 'River'
+  | 'Pond'
+  | 'River (clifftop)'
+  | 'River (mouth)'
+  | 'Sea'
+  | 'Pier'
+  | 'Sea (rainy days)';
+
+export type IPeriodOfDay =
+  | 'All day'
+  | '9 AM - 4 PM'
+  | '4 PM - 9 AM'
+  | '9 PM - 4 AM'
+  | '4 AM - 9 PM';
+
+export type IAvailability<T extends IMonth, U extends IPeriodOfDay[]> = {
+  [K in T]?: U;
+};
 export interface IQueryParams {
   hemisphere?: string;
   month?: string;