docs: improved auto-generated openapi docs

With these additional annotations the openapi docs under `/apidoc` and `/private/apidoc` will be improved by adding errors that the requests can return

Signed-off-by: Philip Molares <philip.molares@udo.edu>

src/api/public/alias/alias.controller.ts

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021 The HedgeDoc developers (see AUTHORS file)
+ * SPDX-FileCopyrightText: 2022 The HedgeDoc developers (see AUTHORS file)
  *
  * SPDX-License-Identifier: AGPL-3.0-only
  */
@@ -20,6 +20,7 @@ import {
   ApiOkResponse,
   ApiSecurity,
   ApiTags,
+  ApiUnprocessableEntityResponse,
 } from '@nestjs/swagger';
 
 import { TokenAuthGuard } from '../../../auth/token.strategy';
@@ -31,6 +32,7 @@ import { AliasService } from '../../../notes/alias.service';
 import { NotesService } from '../../../notes/notes.service';
 import { PermissionsService } from '../../../permissions/permissions.service';
 import { User } from '../../../users/user.entity';
+import { unprocessableEntityDescription } from '../../utils/descriptions';
 import { FullApi } from '../../utils/fullapi-decorator';
 import { RequestUser } from '../../utils/request-user.decorator';
 
@@ -101,6 +103,9 @@ export class AliasController {
     description: 'The alias was deleted',
   })
   @FullApi
+  @ApiUnprocessableEntityResponse({
+    description: unprocessableEntityDescription,
+  })
   async removeAlias(
     @RequestUser() user: User,
     @Param('alias') alias: string,

src/api/public/media/media.controller.ts

@@ -16,12 +16,15 @@ import {
 } from '@nestjs/common';
 import { FileInterceptor } from '@nestjs/platform-express';
 import {
+  ApiBadRequestResponse,
   ApiBody,
   ApiConsumes,
   ApiCreatedResponse,
   ApiForbiddenResponse,
   ApiHeader,
+  ApiInternalServerErrorResponse,
   ApiNoContentResponse,
+  ApiNotFoundResponse,
   ApiSecurity,
   ApiTags,
   ApiUnauthorizedResponse,
@@ -37,7 +40,10 @@ import { Note } from '../../../notes/note.entity';
 import { NotesService } from '../../../notes/notes.service';
 import { User } from '../../../users/user.entity';
 import {
+  badRequestDescription,
   forbiddenDescription,
+  internalServerErrorDescription,
+  notFoundDescription,
   successfullyDeletedDescription,
   unauthorizedDescription,
 } from '../../utils/descriptions';
@@ -78,8 +84,13 @@ export class MediaController {
     description: 'The file was uploaded successfully',
     type: MediaUploadUrlDto,
   })
+  @ApiBadRequestResponse({ description: badRequestDescription })
   @ApiUnauthorizedResponse({ description: unauthorizedDescription })
   @ApiForbiddenResponse({ description: forbiddenDescription })
+  @ApiNotFoundResponse({ description: notFoundDescription })
+  @ApiInternalServerErrorResponse({
+    description: internalServerErrorDescription,
+  })
   @UseInterceptors(FileInterceptor('file'))
   @HttpCode(201)
   async uploadMedia(
@@ -100,6 +111,9 @@ export class MediaController {
   @Delete(':filename')
   @HttpCode(204)
   @ApiNoContentResponse({ description: successfullyDeletedDescription })
+  @ApiInternalServerErrorResponse({
+    description: internalServerErrorDescription,
+  })
   @FullApi
   async deleteMedia(
     @RequestUser() user: User,

src/api/public/notes/notes.controller.ts

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021 The HedgeDoc developers (see AUTHORS file)
+ * SPDX-FileCopyrightText: 2022 The HedgeDoc developers (see AUTHORS file)
  *
  * SPDX-License-Identifier: AGPL-3.0-only
  */
@@ -17,8 +17,11 @@ import {
   UseInterceptors,
 } from '@nestjs/common';
 import {
+  ApiBadRequestResponse,
+  ApiConflictResponse,
   ApiCreatedResponse,
   ApiForbiddenResponse,
+  ApiInternalServerErrorResponse,
   ApiNoContentResponse,
   ApiOkResponse,
   ApiProduces,
@@ -48,7 +51,10 @@ import { RevisionDto } from '../../../revisions/revision.dto';
 import { RevisionsService } from '../../../revisions/revisions.service';
 import { User } from '../../../users/user.entity';
 import {
+  badRequestDescription,
+  conflictDescription,
   forbiddenDescription,
+  internalServerErrorDescription,
   successfullyDeletedDescription,
   unauthorizedDescription,
 } from '../../utils/descriptions';
@@ -115,6 +121,8 @@ export class NotesController {
     description: 'Get information about the newly created note',
     type: NoteDto,
   })
+  @ApiBadRequestResponse({ description: badRequestDescription })
+  @ApiConflictResponse({ description: conflictDescription })
   @ApiUnauthorizedResponse({ description: unauthorizedDescription })
   @ApiForbiddenResponse({ description: forbiddenDescription })
   async createNamedNote(
@@ -135,6 +143,9 @@ export class NotesController {
   @HttpCode(204)
   @ApiNoContentResponse({ description: successfullyDeletedDescription })
   @FullApi
+  @ApiInternalServerErrorResponse({
+    description: internalServerErrorDescription,
+  })
   async deleteNote(
     @RequestUser() user: User,
     @RequestNote() note: Note,