docs(update): update the docs to make better use of @api Body, Para…

…m & Query features
wangdeer · Apr 20, 2022 · dd17f91 · dd17f91
1 parent 879a755
commit dd17f91
Show file tree

Hide file tree

Showing 28 changed files with 134 additions and 43 deletions.
diff --git a/app/Containers/AppSection/Authentication/UI/API/Routes/ForgotPassword.v1.public.php b/app/Containers/AppSection/Authentication/UI/API/Routes/ForgotPassword.v1.public.php
@@ -10,8 +10,10 @@
  * @apiVersion         1.0.0
  * @apiPermission      none
  *
- * @apiParam           {String}  email
- * @apiParam           {String="reset-password"}  reseturl the reset password url
+ * @apiHeader          {String} accept=application/json
+ *
+ * @apiBody           {String}  email
+ * @apiBody           {String="reset-password"}  reseturl the reset password url
  *
  * @apiSuccessExample  {json}  Success-Response:
  * HTTP/1.1 204 No Content

diff --git a/app/Containers/AppSection/Authentication/UI/API/Routes/GetAuthenticatedUser.v1.private.php b/app/Containers/AppSection/Authentication/UI/API/Routes/GetAuthenticatedUser.v1.private.php
@@ -7,6 +7,9 @@
  * @api                {GET} /v1/profile Get Profile
  * @apiDescription     Find the user details of the logged-in user from its Token. (without specifying his ID)
  *
+ * @apiHeader          {String} accept=application/json
+ * @apiHeader          {String} authorization=Bearer
+ *
  * @apiVersion         1.0.0
  * @apiPermission      Authenticated ['permissions' => '', 'roles' => '']
  *

diff --git a/app/Containers/AppSection/Authentication/UI/API/Routes/LoginProxyForWebClient.v1.public.php b/app/Containers/AppSection/Authentication/UI/API/Routes/LoginProxyForWebClient.v1.public.php
@@ -9,8 +9,10 @@
  * @apiVersion         1.0.0
  * @apiPermission      none
  *
- * @apiParam           {String} email
- * @apiParam           {String} password
+ * @apiHeader          {String} accept=application/json
+ *
+ * @apiBody           {String} email
+ * @apiBody           {String} password
  *
  * @apiSuccessExample  {json}       Success-Response:
  * HTTP/1.1 200 OK

diff --git a/...ontainers/AppSection/Authentication/UI/API/Routes/LoginUsingCredentialGrant.v1.public.php b/...ontainers/AppSection/Authentication/UI/API/Routes/LoginUsingCredentialGrant.v1.public.php
@@ -10,10 +10,12 @@
  * @apiVersion         1.0.0
  * @apiPermission      none
  *
- * @apiParam           {String}  client_id
- * @apiParam           {String}  client_secret
- * @apiParam           {String}  grant_type must be `client_credentials`
- * @apiParam           {String}  [scope] you can leave it empty
+ * @apiHeader          {String} accept=application/json
+ *
+ * @apiBody           {String}  client_id
+ * @apiBody           {String}  client_secret
+ * @apiBody           {String}  grant_type must be `client_credentials`
+ * @apiBody           {String}  [scope] you can leave it empty
  *
  * @apiSuccessExample  {json}       Success-Response:
  * HTTP/1.1 200 OK

diff --git a/...Containers/AppSection/Authentication/UI/API/Routes/LoginUsingPasswordGrant.v1.private.php b/...Containers/AppSection/Authentication/UI/API/Routes/LoginUsingPasswordGrant.v1.private.php
@@ -9,12 +9,14 @@
  * @apiVersion         1.0.0
  * @apiPermission      none
  *
- * @apiParam           {String}  username user email
- * @apiParam           {String}  password user password
- * @apiParam           {String}  client_id
- * @apiParam           {String}  client_secret
- * @apiParam           {String}  grant_type must be `password`
- * @apiParam           {String}  [scope] you can leave it empty
+ * @apiHeader          {String} accept=application/json
+ *
+ * @apiBody           {String}  username user email
+ * @apiBody           {String}  password user password
+ * @apiBody           {String}  client_id
+ * @apiBody           {String}  client_secret
+ * @apiBody           {String}  grant_type must be `password`
+ * @apiBody           {String}  [scope] you can leave it empty
  *
  * @apiSuccessExample  {json}       Success-Response:
  * HTTP/1.1 200 OK

diff --git a/app/Containers/AppSection/Authentication/UI/API/Routes/Logout.v1.public.php b/app/Containers/AppSection/Authentication/UI/API/Routes/Logout.v1.public.php
@@ -8,6 +8,9 @@
  * @apiVersion         1.0.0
  * @apiPermission      Authenticated ['permissions' => '', 'roles' => '']
  *
+ * @apiHeader          {String} accept=application/json
+ * @apiHeader          {String} authorization=Bearer
+ *
  * @apiSuccessExample  {json}       Success-Response:
  * HTTP/1.1 202 Accepted
  * {

diff --git a/...Containers/AppSection/Authentication/UI/API/Routes/RefreshProxyForWebClient.v1.public.php b/...Containers/AppSection/Authentication/UI/API/Routes/RefreshProxyForWebClient.v1.public.php
@@ -9,7 +9,9 @@
  * @apiVersion         1.0.0
  * @apiPermission      none
  *
- * @apiParam           {String}  [refresh_token] The refresh Token
+ * @apiHeader          {String} accept=application/json
+ *
+ * @apiBody           {String}  [refresh_token] The refresh Token
  *
  * @apiSuccessExample  {json}       Success-Response:
  * HTTP/1.1 200 OK

diff --git a/app/Containers/AppSection/Authentication/UI/API/Routes/RegisterUser.v1.private.php b/app/Containers/AppSection/Authentication/UI/API/Routes/RegisterUser.v1.private.php
@@ -9,8 +9,10 @@
  * @apiVersion         1.0.0
  * @apiPermission      none
  *
- * @apiParam           {String} email
- * @apiParam           {String} password min: 8
+ * @apiHeader          {String} accept=application/json
+ *
+ * @apiBody           {String} email
+ * @apiBody           {String} password min: 8
  *
  * at least one character of the following:
  *

diff --git a/app/Containers/AppSection/Authentication/UI/API/Routes/ResetPassword.v1.public.php b/app/Containers/AppSection/Authentication/UI/API/Routes/ResetPassword.v1.public.php
@@ -10,9 +10,11 @@
  * @apiVersion         1.0.0
  * @apiPermission      none
  *
- * @apiParam           {String} email
- * @apiParam           {String} token from the forgot password email
- * @apiParam           {String} password min: 8
+ * @apiHeader          {String} accept=application/json
+ *
+ * @apiBody           {String} email
+ * @apiBody           {String} token from the forgot password email
+ * @apiBody           {String} password min: 8
  *
  * at least one character of the following:
  *

diff --git a/app/Containers/AppSection/Authentication/UI/API/Routes/SendVerificationEmail.v1.public.php b/app/Containers/AppSection/Authentication/UI/API/Routes/SendVerificationEmail.v1.public.php
@@ -15,7 +15,7 @@
  *
  * @apiPermission      Authenticated ['permissions' => '', 'roles' => '']
  *
- * @apiParam           {String} verification_url required|url
+ * @apiBody           {String} verification_url required|url
  *
  * @apiSuccessExample  {json} Success-Response:
  * HTTP/1.1 202 Accepted

diff --git a/app/Containers/AppSection/Authentication/UI/API/Routes/VerifyEmail.v1.public.php b/app/Containers/AppSection/Authentication/UI/API/Routes/VerifyEmail.v1.public.php
@@ -7,15 +7,21 @@
  * @api                {POST} /v1/email/verify/:id/:hash Verify Email
  * @apiDescription     Verify user email
  *
- * Value of `url` query string in the verification link (sent to the user by email) should be directly used to call the api and verify the user
+ * Example of a verification email link sent to the user which is used to verify the user `http://apiato.test/email/verify?url=http://api.apiato.test/v1/email/verify/XbPW7awNkzl83LD6/eaabd911e2e07ede6456d3bd5725c6d4a5c2dc0b?expires=1646913047&signature=232702865b8353c445b39c50397e66db33c74df80e3db5a7c0d46ef94c8ab6a9`
  *
- * example of a verification email link sent to the user which is used to verify the use `http://apiato.test/email/verify?url=http://api.apiato.test/v1/email/verify/XbPW7awNkzl83LD6/eaabd911e2e07ede6456d3bd5725c6d4a5c2dc0b?expires=1646913047&signature=232702865b8353c445b39c50397e66db33c74df80e3db5a7c0d46ef94c8ab6a9`
+ * Value of `url` query string in the verification link above (sent to the user by email) can be directly used to call the api to verify the user.
  *
  * @apiVersion         1.0.0
  * @apiPermission      none
  *
  * @apiHeader          {String} accept=application/json
  *
+ * @apiParam           {String} id user id
+ * @apiParam           {String} hash a hashed value sent to the user email
+ *
+ * @apiQuery           {string} expires expiration time of the `verify email` link
+ * @apiQuery           {string} signature a signature to check the validity of the `verify email` link
+ *
  * @apiSuccessExample  {json} Success-Response:
  * HTTP/1.1 200 OK
  * {}

diff --git a/app/Containers/AppSection/Authorization/UI/API/Routes/AssignRolesToUser.v1.private.php b/app/Containers/AppSection/Authorization/UI/API/Routes/AssignRolesToUser.v1.private.php
@@ -13,8 +13,11 @@
  * @apiVersion         1.0.0
  * @apiPermission      Authenticated ['permissions' => 'manage-admins-access', 'roles' => '']
  *
- * @apiParam           {Number} user_id User ID
- * @apiParam           {Array} roles_ids Role ID or Array of Roles ID's
+ * @apiHeader          {String} accept=application/json
+ * @apiHeader          {String} authorization=Bearer
+ *
+ * @apiBody           {Number} user_id User ID
+ * @apiBody           {Array} roles_ids Role ID or Array of Roles ID's
  *
  * @apiUse             UserSuccessSingleResponse
  */

diff --git a/app/Containers/AppSection/Authorization/UI/API/Routes/AttachPermissionsToRole.v1.private.php b/app/Containers/AppSection/Authorization/UI/API/Routes/AttachPermissionsToRole.v1.private.php
@@ -13,8 +13,11 @@
  * @apiVersion         1.0.0
  * @apiPermission      Authenticated ['permissions' => 'manage-roles', 'roles' => '']
  *
- * @apiParam           {String} role_id Role ID
- * @apiParam           {Array} permissions_ids Permission ID or Array of Permissions ID's
+ * @apiHeader          {String} accept=application/json
+ * @apiHeader          {String} authorization=Bearer
+ *
+ * @apiBody           {String} role_id Role ID
+ * @apiBody           {Array} permissions_ids Permission ID or Array of Permissions ID's
  *
  * @apiUse             RoleSuccessSingleResponse
  */

diff --git a/app/Containers/AppSection/Authorization/UI/API/Routes/CreateRole.v1.private.php b/app/Containers/AppSection/Authorization/UI/API/Routes/CreateRole.v1.private.php
@@ -8,9 +8,12 @@
  * @apiVersion         1.0.0
  * @apiPermission      Authenticated ['permissions' => 'manage-roles', 'roles' => '']
  *
- * @apiParam           {String} name Unique Role Name
- * @apiParam           {String} [description]
- * @apiParam           {String} [display_name]
+ * @apiHeader          {String} accept=application/json
+ * @apiHeader          {String} authorization=Bearer
+ *
+ * @apiBody           {String} name Unique Role Name
+ * @apiBody           {String} [description]
+ * @apiBody           {String} [display_name]
  *
  * @apiUse             RoleSuccessSingleResponse
  */

diff --git a/app/Containers/AppSection/Authorization/UI/API/Routes/DeleteRole.v1.private.php b/app/Containers/AppSection/Authorization/UI/API/Routes/DeleteRole.v1.private.php
@@ -9,6 +9,11 @@
  * @apiVersion         1.0.0
  * @apiPermission      Authenticated ['permissions' => 'manage-roles', 'roles' => '']
  *
+ * @apiHeader          {String} accept=application/json
+ * @apiHeader          {String} authorization=Bearer
+ *
+ * @apiParam           {String} id role id
+ *
  * @apiSuccessExample  {json}       Success-Response:
  * HTTP/1.1 202 OK
  * {

diff --git a/...ontainers/AppSection/Authorization/UI/API/Routes/DetachPermissionsFromRole.v1.private.php b/...ontainers/AppSection/Authorization/UI/API/Routes/DetachPermissionsFromRole.v1.private.php
@@ -13,8 +13,11 @@
  * @apiVersion         1.0.0
  * @apiPermission      Authenticated ['permissions' => 'manage-roles', 'roles' => '']
  *
- * @apiParam           {String} role_id Role ID
- * @apiParam           {String-Array} permissions_ids Permission ID or Array of Permissions ID's
+ * @apiHeader          {String} accept=application/json
+ * @apiHeader          {String} authorization=Bearer
+ *
+ * @apiBody           {String} role_id Role ID
+ * @apiBody           {String-Array} permissions_ids Permission ID or Array of Permissions ID's
  *
  * @apiUse             RoleSuccessSingleResponse
  */

diff --git a/app/Containers/AppSection/Authorization/UI/API/Routes/FindPermission.v1.private.php b/app/Containers/AppSection/Authorization/UI/API/Routes/FindPermission.v1.private.php
@@ -8,6 +8,11 @@
  * @apiVersion         1.0.0
  * @apiPermission      Authenticated ['permissions' => 'manage-roles', 'roles' => '']
  *
+ * @apiHeader          {String} accept=application/json
+ * @apiHeader          {String} authorization=Bearer
+ *
+ * @apiParam           {String} id permission id
+ *
  * @apiUse             PermissionSuccessSingleResponse
  */
 

diff --git a/app/Containers/AppSection/Authorization/UI/API/Routes/FindRole.v1.private.php b/app/Containers/AppSection/Authorization/UI/API/Routes/FindRole.v1.private.php
@@ -8,6 +8,11 @@
  * @apiVersion         1.0.0
  * @apiPermission      Authenticated ['permissions' => 'manage-roles', 'roles' => '']
  *
+ * @apiHeader          {String} accept=application/json
+ * @apiHeader          {String} authorization=Bearer
+ *
+ * @apiParam           {String} id role id
+ *
  * @apiUse             RoleSuccessSingleResponse
  */
 

diff --git a/app/Containers/AppSection/Authorization/UI/API/Routes/GetAllPermissions.v1.private.php b/app/Containers/AppSection/Authorization/UI/API/Routes/GetAllPermissions.v1.private.php
@@ -8,6 +8,9 @@
  * @apiVersion         1.0.0
  * @apiPermission      Authenticated ['permissions' => 'manage-roles', 'roles' => '']
  *
+ * @apiHeader          {String} accept=application/json
+ * @apiHeader          {String} authorization=Bearer
+ *
  * @apiUse             GeneralSuccessMultipleResponse
  */
 

diff --git a/app/Containers/AppSection/Authorization/UI/API/Routes/GetAllRoles.v1.private.php b/app/Containers/AppSection/Authorization/UI/API/Routes/GetAllRoles.v1.private.php
@@ -8,6 +8,9 @@
  * @apiVersion         1.0.0
  * @apiPermission      Authenticated ['permissions' => 'manage-roles', 'roles' => '']
  *
+ * @apiHeader          {String} accept=application/json
+ * @apiHeader          {String} authorization=Bearer
+ *
  * @apiUse             GeneralSuccessMultipleResponse
  */
 

diff --git a/app/Containers/AppSection/Authorization/UI/API/Routes/RevokeRolesFromUser.v1.private.php b/app/Containers/AppSection/Authorization/UI/API/Routes/RevokeRolesFromUser.v1.private.php
@@ -13,8 +13,11 @@
  * @apiVersion         1.0.0
  * @apiPermission      Authenticated ['permissions' => 'manage-admins-access', 'roles' => '']
  *
- * @apiParam           {Number} user_id user ID
- * @apiParam           {Array} roles_ids Role ID or Array of Role ID's
+ * @apiHeader          {String} accept=application/json
+ * @apiHeader          {String} authorization=Bearer
+ *
+ * @apiBody           {Number} user_id user ID
+ * @apiBody           {Array} roles_ids Role ID or Array of Role ID's
  *
  * @apiUse             UserSuccessSingleResponse
  */

diff --git a/app/Containers/AppSection/Authorization/UI/API/Routes/SyncPermissionOnRole.v1.private.php b/app/Containers/AppSection/Authorization/UI/API/Routes/SyncPermissionOnRole.v1.private.php
@@ -10,8 +10,11 @@
  * @apiVersion         1.0.0
  * @apiPermission      Authenticated ['permissions' => 'manage-roles', 'roles' => '']
  *
- * @apiParam           {String} role_id Role ID
- * @apiParam           {Array} permissions_ids Permission ID or Array of Permissions ID's
+ * @apiHeader          {String} accept=application/json
+ * @apiHeader          {String} authorization=Bearer
+ *
+ * @apiBody           {String} role_id Role ID
+ * @apiBody           {Array} permissions_ids Permission ID or Array of Permissions ID's
  *
  * @apiUse             RoleSuccessSingleResponse
  */

diff --git a/app/Containers/AppSection/Authorization/UI/API/Routes/SyncUserRoles.v1.private.php b/app/Containers/AppSection/Authorization/UI/API/Routes/SyncUserRoles.v1.private.php
@@ -11,8 +11,11 @@
  * @apiVersion         1.0.0
  * @apiPermission      Authenticated ['permissions' => 'manage-admins-access', 'roles' => '']
  *
- * @apiParam           {Number} user_id User ID
- * @apiParam           {Array} roles_ids Role ID or Array of Roles ID's
+ * @apiHeader          {String} accept=application/json
+ * @apiHeader          {String} authorization=Bearer
+ *
+ * @apiBody           {Number} user_id User ID
+ * @apiBody           {Array} roles_ids Role ID or Array of Roles ID's
  *
  * @apiUse             UserSuccessSingleResponse
  */

diff --git a/app/Containers/AppSection/User/UI/API/Routes/DeleteUser.v1.private.php b/app/Containers/AppSection/User/UI/API/Routes/DeleteUser.v1.private.php
@@ -9,6 +9,11 @@
  * @apiVersion         1.0.0
  * @apiPermission      Authenticated ['permissions' => 'delete-users', 'roles' => ''] | Resource Owner
  *
+ * @apiHeader          {String} accept=application/json
+ * @apiHeader          {String} authorization=Bearer
+ *
+ * @apiParam           {String} id user id
+ *
  * @apiSuccessExample  {json}       Success-Response:
  * HTTP/1.1 204 No Content
  * {}

diff --git a/app/Containers/AppSection/User/UI/API/Routes/FindUserById.v1.private.php b/app/Containers/AppSection/User/UI/API/Routes/FindUserById.v1.private.php
@@ -9,6 +9,11 @@
  * @apiVersion         1.0.0
  * @apiPermission      Authenticated ['permissions' => 'search-users', 'roles' => '']
  *
+ * @apiHeader          {String} accept=application/json
+ * @apiHeader          {String} authorization=Bearer
+ *
+ * @apiParam           {String} id user id
+ *
  * @apiUse             UserSuccessSingleResponse
  */
 

diff --git a/app/Containers/AppSection/User/UI/API/Routes/GetAllUsers.v1.private.php b/app/Containers/AppSection/User/UI/API/Routes/GetAllUsers.v1.private.php
@@ -10,6 +10,9 @@
  * @apiVersion         1.0.0
  * @apiPermission      Authenticated ['permissions' => 'list-users', 'roles' => ''] | Resource Owner
  *
+ * @apiHeader          {String} accept=application/json
+ * @apiHeader          {String} authorization=Bearer
+ *
  * @apiUse             GeneralSuccessMultipleResponse
  */
 

diff --git a/app/Containers/AppSection/User/UI/API/Routes/UpdateUser.v1.private.php b/app/Containers/AppSection/User/UI/API/Routes/UpdateUser.v1.private.php
@@ -8,9 +8,14 @@
  * @apiVersion         1.0.0
  * @apiPermission      Authenticated ['permissions' => 'update-users', 'roles' => ''] | Resource Owner
  *
- * @apiParam           {String} [name] min:2|max:50
- * @apiParam           {String="male","female","unspecified"} [gender]
- * @apiParam           {Date} [birth] format: Y-m-d / e.g. 2015-10-15
+ * @apiHeader          {String} accept=application/json
+ * @apiHeader          {String} authorization=Bearer
+ *
+ * @apiParam           {String} id user id
+ *
+ * @apiBody           {String} [name] min:2|max:50
+ * @apiBody           {String="male","female","unspecified"} [gender]
+ * @apiBody           {Date} [birth] format: Y-m-d / e.g. 2015-10-15
  *
  * @apiUse             UserSuccessSingleResponse
  */

diff --git a/app/Containers/AppSection/User/UI/API/Routes/UpdateUserPassword.v1.private.php b/app/Containers/AppSection/User/UI/API/Routes/UpdateUserPassword.v1.private.php
@@ -8,8 +8,13 @@
  * @apiVersion         1.0.0
  * @apiPermission      Authenticated ['permissions' => 'update-users', 'roles' => ''] | Resource Owner
  *
- * @apiParam           {String} current_password
- * @apiParam           {String} new_password min: 8
+ * @apiHeader          {String} accept=application/json
+ * @apiHeader          {String} authorization=Bearer
+ *
+ * @apiParam           {String} id user id
+ *
+ * @apiBody           {String} current_password
+ * @apiBody           {String} new_password min: 8
  *
  * at least one character of the following:
  *