From 05319e6f6ea10676281f2a05aad95cdca4d156ba Mon Sep 17 00:00:00 2001
From: Nicolai Ort <info@nicolai-ort.com>
Date: Tue, 22 Dec 2020 19:51:37 +0100
Subject: [PATCH] Updated the openapi descriptions for all permission routes

ref #49
---
 src/controllers/PermissionController.ts | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/controllers/PermissionController.ts b/src/controllers/PermissionController.ts
index 4d04db2..71e90eb 100644
--- a/src/controllers/PermissionController.ts
+++ b/src/controllers/PermissionController.ts
@@ -26,7 +26,7 @@ export class PermissionController {
     @Get()
     @Authorized("PERMISSION:GET")
     @ResponseSchema(ResponsePermission, { isArray: true })
-    @OpenAPI({ description: 'Lists all permissions.' })
+    @OpenAPI({ description: 'Lists all permissions for all users and groups.' })
     async getAll() {
         let responsePermissions: ResponsePermission[] = new Array<ResponsePermission>();
         const permissions = await this.permissionRepository.find({ relations: ['principal'] });
@@ -42,7 +42,7 @@ export class PermissionController {
     @ResponseSchema(ResponsePermission)
     @ResponseSchema(PermissionNotFoundError, { statusCode: 404 })
     @OnUndefined(PermissionNotFoundError)
-    @OpenAPI({ description: 'Returns a permissions of a specified id (if it exists)' })
+    @OpenAPI({ description: 'Lists all information about the permission whose id got provided.' })
     async getOne(@Param('id') id: number) {
         let permission = await this.permissionRepository.findOne({ id: id }, { relations: ['principal'] });
         if (!permission) { throw new PermissionNotFoundError(); }
@@ -54,7 +54,7 @@ export class PermissionController {
     @Authorized("PERMISSION:CREATE")
     @ResponseSchema(ResponsePermission)
     @ResponseSchema(PrincipalNotFoundError, { statusCode: 404 })
-    @OpenAPI({ description: 'Create a new runnerTeam object (id will be generated automagicly).' })
+    @OpenAPI({ description: 'Create a new permission for a existing principal(user/group). <br> If a permission with this target, action and prinicpal already exists that permission will be returned instead of creating a new one.' })
     async post(@Body({ validate: true }) createPermission: CreatePermission) {
         let permission;
         try {
@@ -79,7 +79,7 @@ export class PermissionController {
     @ResponseSchema(PrincipalNotFoundError, { statusCode: 404 })
     @ResponseSchema(PermissionIdsNotMatchingError, { statusCode: 406 })
     @ResponseSchema(PermissionNeedsPrincipalError, { statusCode: 406 })
-    @OpenAPI({ description: "Update a permission object (id can't be changed)." })
+    @OpenAPI({ description: "Update a permission object. <br> If updateing the permission object would result in duplicate permission (same target, action and principal) this permission will get deleted and the existing permission will be returned. <br> Please remember that id's can't be changed." })
     async put(@Param('id') id: number, @Body({ validate: true }) permission: UpdatePermission) {
         let oldPermission = await this.permissionRepository.findOne({ id: id }, { relations: ['principal'] });
 
@@ -106,7 +106,7 @@ export class PermissionController {
     @ResponseSchema(ResponsePermission)
     @ResponseSchema(ResponseEmpty, { statusCode: 204 })
     @OnUndefined(204)
-    @OpenAPI({ description: 'Delete a specified permission (if it exists).' })
+    @OpenAPI({ description: 'Deletes the permission whose id you provide. <br> If no permission with this id exists it will just return 204(no content).' })
     async remove(@Param("id") id: number, @QueryParam("force") force: boolean) {
         let permission = await this.permissionRepository.findOne({ id: id }, { relations: ['principal'] });
         if (!permission) { return null; }