Commit cfbab6f2 authored by Jacob Priddy's avatar Jacob Priddy 👌
Browse files

Doors and users api docs

parent 60accc37
......@@ -70,6 +70,8 @@ class DoorsController extends ApiController
*
* @authenticated
*
* @response 404 {"status":"error","code":404,"message":"Entity not found"}
*
* @param \Source\UseCases\Doors\GetDoor\GetDoorUseCase $getDoor
* @param string $doorId
* @return \Illuminate\Http\JsonResponse
......
......@@ -33,6 +33,15 @@ use Source\UseCases\GroupUser\RemoveUserFromGroup\APIPresenter as RemoveUserFrom
class UsersController extends ApiController
{
/**
* List/Search Users
*
* This endpoint can list/search/query the list of users. If the parameter is not given it returns a paginated list
* of all doors
*
* @authenticated
* @paginated
* @queryParam query Searches for first, last, and display names as well as email and peoplesoft employee id.
*
* @param \Source\UseCases\Users\GetUsers\GetUsersUseCase $getAllUsers
* @return \Illuminate\Http\JsonResponse
* @throws \Source\Exceptions\AuthorizationException
......@@ -44,7 +53,7 @@ class UsersController extends ApiController
$this->authorizer->protect(Permissions::MANAGE_USERS);
$this->validate($this->request, [
'query' => 'string'
'query' => 'string',
]);
$presenter = new AllUsersAPIPresenter();
......@@ -57,6 +66,12 @@ class UsersController extends ApiController
}
/**
* Get User
*
* This endpoint gets a specific user and returns information relating directly to the user.
*
* @response 404 {"status":"error","code":404,"message":"Entity not found"}
*
* @param \Source\UseCases\Users\GetUser\GetUserUseCase $getUser
* @param string $userId
* @return \Illuminate\Http\JsonResponse
......@@ -75,6 +90,24 @@ class UsersController extends ApiController
}
/**
* Create User
*
* This endpoint creates a new user in the system. The user cannot share an email emplid, or doorcode with
* any otheres
*
* @authenticated
* @bodyParam first_name string required The first name of the user. Example: George
* @bodyParam last_name string required The last name of the user. Example: Amalor
* @bodyParam display_name string required The display name of the user. Example: Himie Horghe
* @bodyParam email string required The users email. Example: gg@gg.com
* @bodyParam emplid string The users employee id. Example: 239990
* @bodyParam password string The users local application password. Example: This is a better password than 99%
* @bodyParam doorcode string The users doorcode used to access doors. Example: 177478
* @bodyParam expires_at date The users expiry date after which they will not be able to access doors or login.
*
* @response 400
* {"status":"error","code":400,"message":"User already exists!"}
*
* @param \Source\UseCases\Users\CreateUser\CreateUserUseCase $createUser
* @return \Illuminate\Http\JsonResponse
* @throws \Illuminate\Validation\ValidationException
......@@ -107,6 +140,25 @@ class UsersController extends ApiController
}
/**
* Update User
*
* This endpoint updates an existing user in the system. The user cannot share an email emplid, or doorcode with
* any others
*
* @authenticated
* @urlParam userId required The id of the user to update. Example: 69
* @bodyParam first_name string The first name of the user. Example: George
* @bodyParam last_name string The last name of the user. Example: Amalor
* @bodyParam display_name string The display name of the user. Example: Himie Horghe
* @bodyParam email string The users email. Example: gg@gg.com
* @bodyParam emplid string The users employee id. Example: 239990
* @bodyParam password string The users local application password. Example: This is a better password than 99%
* @bodyParam doorcode string The users doorcode used to access doors. Example: 177478
* @bodyParam expires_at date The users expiry date after which they will not be able to access doors or login.
*
* @response 400
* {"status":"error","code":400,"message":"User with that email already exists."}
*
* @param \Source\UseCases\Users\UpdateUser\UpdateUserUseCase $updateUser
* @param string $userId
* @return \Illuminate\Http\JsonResponse
......@@ -119,11 +171,11 @@ class UsersController extends ApiController
$this->authorizer->protect(Permissions::MANAGE_USERS);
$this->validate($this->request, [
'first_name' => 'string|max:255',
'last_name' => 'string|max:255',
'display_name' => 'string|max:255',
'first_name' => 'nullable|string|max:255',
'last_name' => 'nullable|string|max:255',
'display_name' => 'nullable|string|max:255',
'emplid' => 'nullable|string|max:8|min:5',
'email' => 'email|max:255',
'email' => 'nullable|email|max:255',
'password' => 'nullable|string|max:255',
'doorcode' => 'nullable|string|numeric|digits_between:4,255',
'expires_at' => 'nullable|string|date|max:255',
......@@ -150,6 +202,8 @@ class UsersController extends ApiController
* @authenticated
* @urlParam userId required The userId to delete. Example: 2
*
* @response 403 {"message":"You cannot modify the admin user."}
* @response 403 {"message":"You cannot delete yourself!"}
*
* @param \Source\UseCases\Users\DeleteUser\DeleteUserUseCase $deleteUser
* @param string $userId
......@@ -167,6 +221,7 @@ class UsersController extends ApiController
$deleteUser->delete($userId, $presenter);
} catch (DeleteFailedException $e) {
$this->setStatusCode(400);
return $this->respondWithError($e->getMessage());
}
......@@ -174,6 +229,12 @@ class UsersController extends ApiController
}
/**
* Add user to group
*
* This route adds a user to a group
*
* @authenticated
*
* @param \Source\UseCases\GroupUser\AddUserToGroup\AddUserToGroupUseCase $useCase
* @param string $userId
* @param string $groupId
......@@ -197,6 +258,8 @@ class UsersController extends ApiController
*
* This route removes a user from a group.
*
* @authenticated
*
* @param \Source\UseCases\GroupUser\RemoveUserFromGroup\RemoveUserFromGroupUseCase $useCase
* @param string $userId
* @param string $groupId
......@@ -216,6 +279,15 @@ class UsersController extends ApiController
}
/**
* User Groups
*
* This endpoint gets all groups for a user.
*
* @urlParam userId required The ID of the user to get.
*
* @authenticated
* @paginated
*
* @param \Source\UseCases\GroupUser\GetUserGroups\GetUserGroupsUseCase $useCase
* @param string $userId
* @return \Illuminate\Http\JsonResponse
......@@ -234,6 +306,14 @@ class UsersController extends ApiController
}
/**
* User Doors
*
* This endpoint gets all the doors that a user has access too as well as the access schedules for those doors and
* what groups give these permissions.
*
* @authenticaetd
* @urlParam userId required The ID of the user to get access data for. Example: 420
*
* @param \Source\UseCases\DoorUser\UserDoorAccess\UserDoorAccessUseCase $userDoorAccessUseCase
* @param string $userId
* @return \Illuminate\Http\JsonResponse
......
......@@ -392,11 +392,11 @@ return [
],
'responses' => [
\App\Documentation\Strategies\ApplicationRepositoryResetStrategy::class,
\Mpociot\ApiDoc\Extracting\Strategies\Responses\UseTransformerTags::class,
\Mpociot\ApiDoc\Extracting\Strategies\Responses\ResponseCalls::class,
\Mpociot\ApiDoc\Extracting\Strategies\Responses\UseResponseTag::class,
\Mpociot\ApiDoc\Extracting\Strategies\Responses\UseResponseFileTag::class,
\Mpociot\ApiDoc\Extracting\Strategies\Responses\UseTransformerTags::class,
\Mpociot\ApiDoc\Extracting\Strategies\Responses\UseApiResourceTags::class,
\Mpociot\ApiDoc\Extracting\Strategies\Responses\ResponseCalls::class,
\Mpociot\ApiDoc\Extracting\Strategies\Responses\UseResponseFileTag::class,
\App\Documentation\Strategies\UnauthenticatedResponseStrategy::class,
],
],
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment