feat(api): add swagger api docs. closes #56

server/package.json

@@ -32,6 +32,7 @@
     "@nestjs/jwt": "^10.0.3",
     "@nestjs/passport": "^9.0.3",
     "@nestjs/platform-express": "^9.0.0",
+    "@nestjs/swagger": "^7.0.2",
     "@nestjs/throttler": "^4.0.0",
     "bcrypt": "^5.1.0",
     "censor-sensor": "^1.0.6",

server/src/main.ts

@@ -1,11 +1,27 @@
 import { NestFactory } from '@nestjs/core';
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
 import { AppModule } from './app.module';
 
 async function bootstrap() {
   const app = await NestFactory.create(AppModule);
   app.enableCors({
     origin: ['http://localhost:3699', 'https://play.ateoat.com'],
   });
+
+  const config = new DocumentBuilder()
+    .setTitle('ateoat API')
+    .setDescription('The ateoat REST API')
+    .setVersion('dev')
+    .build();
+
+  const document = SwaggerModule.createDocument(app, config);
+  SwaggerModule.setup('api', app, document, {
+    swaggerOptions: {
+      tagsSorter: 'alpha',
+      operationsSorter: 'alpha',
+    },
+  });
+
   await app.listen(3000);
 }
 

server/src/modules/achievements/achievements.controller.ts

@@ -1,4 +1,6 @@
 import { Controller } from '@nestjs/common';
+import { ApiBearerAuth } from '@nestjs/swagger';
 
+@ApiBearerAuth()
 @Controller('achievements')
 export class AchievementsController {}

server/src/modules/discoveries/discoveries.controller.ts

@@ -1,4 +1,6 @@
 import { Controller } from '@nestjs/common';
+import { ApiBearerAuth } from '@nestjs/swagger';
 
+@ApiBearerAuth()
 @Controller('discoveries')
 export class DiscoveriesController {}

server/src/modules/inventory/inventory.controller.ts

@@ -1,13 +1,16 @@
 import { JwtAuthGuard } from '@modules/auth/jwt.guard';
 import { InventoryService } from '@modules/inventory/inventory.service';
 import { Controller, Get, UseGuards } from '@nestjs/common';
+import { ApiBearerAuth, ApiOperation } from '@nestjs/swagger';
 import { User } from '@utils/user.decorator';
 
+@ApiBearerAuth()
 @Controller('inventory')
 export class InventoryController {
   constructor(private readonly inventoryService: InventoryService) {}
 
   @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Get my current item list' })
   @Get('items')
   async getItems(@User() user) {
     return {

server/src/modules/notification/notification.controller.ts

@@ -1,13 +1,16 @@
 import { JwtAuthGuard } from '@modules/auth/jwt.guard';
 import { NotificationService } from '@modules/notification/notification.service';
 import { Body, Controller, Get, Post, Query, UseGuards } from '@nestjs/common';
+import { ApiBearerAuth, ApiOperation } from '@nestjs/swagger';
 import { User } from '@utils/user.decorator';
 
+@ApiBearerAuth()
 @Controller('notification')
 export class NotificationController {
   constructor(private readonly notificationService: NotificationService) {}
 
   @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Get all of my current notifications' })
   @Get('/mine')
   async getMyNotifications(@User() user) {
     return {
@@ -18,6 +21,9 @@ export class NotificationController {
   }
 
   @UseGuards(JwtAuthGuard)
+  @ApiOperation({
+    summary: 'Get all of my notifications after a certain timestamp',
+  })
   @Get('/mine/after')
   async getMyNotificationsAfter(@User() user, @Query('after') after: string) {
     if (!after) return this.getMyNotifications(user);
@@ -32,18 +38,21 @@ export class NotificationController {
   }
 
   @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Mark all of my notifications read' })
   @Post('/markallread')
   async markAllRead(@User() user) {
     return this.notificationService.markAllNotificationsRead(user.userId);
   }
 
   @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Mark a specific notification read' })
   @Post('/markread')
   async markRead(@User() user, @Body('notificationId') notificationId: string) {
     return this.notificationService.markNotificationRead(notificationId);
   }
 
   @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Clear the actions from a notification' })
   @Post('/clearactions')
   async clearActions(
     @User() user,

server/src/modules/player/gameplay.controller.ts

@@ -8,8 +8,10 @@ import {
   Post,
   UseGuards,
 } from '@nestjs/common';
+import { ApiBearerAuth, ApiOperation } from '@nestjs/swagger';
 import { User } from '@utils/user.decorator';
 
+@ApiBearerAuth()
 @Controller('gameplay')
 export class GameplayController {
   constructor(
@@ -18,12 +20,14 @@ export class GameplayController {
   ) {}
 
   @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Explore the current location' })
   @Post('explore')
   async explore(@User() user) {
     return this.gameplayService.explore(user.userId);
   }
 
   @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Set a walking path to a new location' })
   @Post('walk')
   async walk(@User() user, @Body('location') location: string) {
     return {
@@ -32,6 +36,7 @@ export class GameplayController {
   }
 
   @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Travel immediately to a new location' })
   @Post('travel')
   async travel(@User() user, @Body('location') location: string) {
     return {
@@ -43,6 +48,7 @@ export class GameplayController {
   }
 
   @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Explore Event: Wave at another player' })
   @Post('wave')
   async wave(
     @User() user,
@@ -59,6 +65,7 @@ export class GameplayController {
   }
 
   @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Explore Event: Take an item' })
   @Post('takeitem')
   async takeitem(@User() user) {
     if (await this.inventoryService.isInventoryFull(user.userId)) {

server/src/modules/player/player.controller.ts

@@ -1,13 +1,16 @@
 import { JwtAuthGuard } from '@modules/auth/jwt.guard';
 import { PlayerService } from '@modules/player/player.service';
 import { Body, Controller, Patch, UseGuards } from '@nestjs/common';
+import { ApiBearerAuth, ApiOperation } from '@nestjs/swagger';
 import { User } from '@utils/user.decorator';
 
+@ApiBearerAuth()
 @Controller('player')
 export class PlayerController {
   constructor(private readonly playerService: PlayerService) {}
 
   @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Get the online users count' })
   @Patch('cosmetics/portrait')
   async changePortrait(@User() user, @Body('portrait') portrait: number) {
     const portraitId = Math.round(Math.min(107, Math.max(0, portrait)));

server/src/modules/stats/stats.controller.ts

@@ -1,4 +1,6 @@
 import { Controller } from '@nestjs/common';
+import { ApiBearerAuth } from '@nestjs/swagger';
 
+@ApiBearerAuth()
 @Controller('stats')
 export class StatsController {}

server/src/modules/user/user.controller.ts

@@ -1,24 +1,29 @@
 import { Controller, Get, Param, UseGuards } from '@nestjs/common';
+import { ApiBearerAuth, ApiOperation } from '@nestjs/swagger';
 import { User } from '../../utils/user.decorator';
 import { JwtAuthGuard } from '../auth/jwt.guard';
 import { UserService } from './user.service';
 
+@ApiBearerAuth()
 @Controller('user')
 export class UserController {
   constructor(private userService: UserService) {}
 
   @Get('online')
+  @ApiOperation({ summary: 'Get the online users count' })
   async onlineUsers() {
     return { users: await this.userService.onlineUsers() };
   }
 
   @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Get my user profile' })
   @Get('profile/me')
   async getMyProfile(@User() user) {
     return { user: await this.userService.findUserById(user.userId) };
   }
 
   @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Get a specific user profile' })
   @Get('profile/:id')
   async getProfile(@Param('id') id: string) {
     return { user: await this.userService.findUserById(id) };