From cfcde6b7a83c5b4657b94f4d654e6a3a432f121d Mon Sep 17 00:00:00 2001 From: Christian Hartmann Date: Mon, 28 Oct 2024 15:07:23 +0100 Subject: [PATCH] add missing status descriptions Signed-off-by: Christian Hartmann --- lib/Controller/ApiController.php | 46 ++++++++++++++++++++- lib/Controller/ShareApiController.php | 6 +++ lib/ResponseDefinitions.php | 2 +- openapi.json | 59 +++++++++++++++------------ 4 files changed, 84 insertions(+), 29 deletions(-) diff --git a/lib/Controller/ApiController.php b/lib/Controller/ApiController.php index cdf3da143..2110c671f 100644 --- a/lib/Controller/ApiController.php +++ b/lib/Controller/ApiController.php @@ -129,6 +129,8 @@ public function preflightedCors() { * - `shared`: Forms shared with the user. * @return DataResponse, array{}> * @throws OCSBadRequestException wrong form type supplied + * + * 200: Array containing the partial owned or shared forms */ #[CORS()] #[NoAdminRequired()] @@ -158,6 +160,8 @@ public function getForms(string $type = 'owned'): DataResponse { * @param ?int $fromId (optional) Id of the form that should be cloned * @return DataResponse * @throws OCSForbiddenException The user is not allowed to create forms + * + * 201: the created form */ #[CORS()] #[NoAdminRequired()] @@ -234,6 +238,8 @@ public function newForm(?int $fromId = null): DataResponse { * @return DataResponse, array{}> * @throws OCSBadRequestException Could not find form * @throws OCSForbiddenException User has no permissions to get this form + * + * 200: the requested form */ #[CORS()] #[NoAdminRequired()] @@ -259,12 +265,14 @@ public function getForm(int $formId): DataResponse { * * @param int $formId FormId of form to update * @param array $keyValuePairs Array of key=>value pairs to update. - * @return DataResponse + * @return DataResponse * @throws OCSBadRequestException Could not find new form owner * @throws OCSForbiddenException Empty keyValuePairs provided * @throws OCSForbiddenException Not allowed to update id, hash, created, fileId or lastUpdated. OwnerId only allowed if no other key provided. * @throws OCSForbiddenException User is not allowed to modify the form * @throws OCSNotFoundException Form not found + * + * 200: the id of the updated form */ #[CORS()] #[NoAdminRequired()] @@ -324,7 +332,7 @@ public function updateForm(int $formId, array $keyValuePairs): DataResponse { } // Process file unlinking - if (key_exists('fileId', $keyValuePairs) && key_exists('fileFormat', $keyValuePairs) && !isset($keyValuePairs['fileId']) && !isset($keyValuePairs['fileFormat'])) { + if (key_exists('fileId', $keyValuePairs) && key_exists('fileFormat', $keyValuePairs) && !isset($keyValuePairs['fileFormat'])) { $form->setFileId(null); $form->setFileFormat(null); } @@ -352,6 +360,8 @@ public function updateForm(int $formId, array $keyValuePairs): DataResponse { * @return DataResponse * @throws OCSForbiddenException User is not allowed to delete the form * @throws OCSNotFoundException Form not found + * + * 200: the id of the deleted form */ #[CORS()] #[NoAdminRequired()] @@ -375,6 +385,8 @@ public function deleteForm(int $formId): DataResponse { * @return DataResponse, array{}> * @throws OCSForbiddenException User has no permissions to get this form * @throws OCSNotFoundException Could not find form + * + * 200: the questions of the given form */ #[CORS()] #[NoAdminRequired()] @@ -406,6 +418,8 @@ public function getQuestions(int $formId): DataResponse { * @throws OCSBadRequestException Question doesn\'t belong to given Form * @throws OCSForbiddenException User has no permissions to get this form * @throws OCSNotFoundException Could not find form + * + * 200: the requested question */ #[CORS()] #[NoAdminRequired()] @@ -446,6 +460,8 @@ public function getQuestion(int $formId, int $questionId): DataResponse { * @throws OCSForbiddenException This form is archived and can not be modified * @throws OCSNotFoundException Could not find form * @throws OCSNotFoundException Could not find question + * + * 201: the created question */ #[CORS()] #[NoAdminRequired()] @@ -559,6 +575,8 @@ public function newQuestion(int $formId, ?string $type = null, string $text = '' * @throws OCSForbiddenException User has no permissions to get this form * @throws OCSNotFoundException Could not find form * @throws OCSNotFoundException Could not find question + * + * 200: the id of the updated question */ #[CORS()] #[NoAdminRequired()] @@ -631,6 +649,8 @@ public function updateQuestion(int $formId, int $questionId, array $keyValuePair * @throws OCSForbiddenException User has no permissions to get this form * @throws OCSNotFoundException Could not find form * @throws OCSNotFoundException Could not find question + * + * 200: the id of the deleted question */ #[CORS()] #[NoAdminRequired()] @@ -693,6 +713,8 @@ public function deleteQuestion(int $formId, int $questionId): DataResponse { * @throws OCSForbiddenException User has no permissions to get this form * @throws OCSNotFoundException Could not find form * @throws OCSNotFoundException Could not find question + * + * 200: the question ids of the given form in the new order */ #[CORS()] #[NoAdminRequired()] @@ -788,6 +810,8 @@ public function reorderQuestions(int $formId, array $newOrder): DataResponse { * @throws OCSForbiddenException Current user has no permission to edit * @throws OCSNotFoundException Could not find form * @throws OCSNotFoundException Could not find question + * + * 201: the created option */ #[CORS()] #[NoAdminRequired()] @@ -866,6 +890,8 @@ public function newOption(int $formId, int $questionId, array $optionTexts): Dat * @throws OCSForbiddenException Not allowed to update id or questionId * @throws OCSNotFoundException Could not find form * @throws OCSNotFoundException Could not find option or question + * + * 200: the id of the updated option */ #[CORS()] #[NoAdminRequired()] @@ -933,6 +959,8 @@ public function updateOption(int $formId, int $questionId, int $optionId, array * @throws OCSForbiddenException Current user has no permission to edit * @throws OCSNotFoundException Could not find form * @throws OCSNotFoundException Could not find question or option + * + * 200: the id of the deleted option */ #[CORS()] #[NoAdminRequired()] @@ -990,6 +1018,8 @@ public function deleteOption(int $formId, int $questionId, int $optionId): DataR * @throws OCSForbiddenException Current user has no permission to edit * @throws OCSNotFoundException Could not find form * @throws OCSNotFoundException Could not find question + * + * 200: the options of the question in the new order */ #[CORS()] #[NoAdminRequired()] @@ -1085,6 +1115,8 @@ public function reorderOptions(int $formId, int $questionId, array $newOrder) { * @return DataResponse|DataDownloadResponse * @throws OCSNotFoundException Could not find form * @throws OCSForbiddenException The current user has no permission to get the results for this form + * + * 200: the submissions of the form */ #[CORS()] #[NoAdminRequired()] @@ -1146,6 +1178,8 @@ public function getSubmissions(int $formId, ?string $fileFormat = null): DataRes * @return DataResponse * @throws OCSNotFoundException Could not find form * @throws OCSForbiddenException This form is not owned by the current user and user has no `results_delete` permission + * + * 200: the form id of the deleted submission */ #[CORS()] #[NoAdminRequired()] @@ -1188,6 +1222,8 @@ public function deleteAllSubmissions(int $formId): DataResponse { * @throws OCSForbiddenException This form is no longer taking answers * @throws OCSForbiddenException This form is not owned by the current user and user has no `results_delete` permission * @throws OCSNotFoundException Could not find form + * + * 201: empty response */ #[CORS()] #[NoAdminRequired()] @@ -1284,6 +1320,8 @@ public function newSubmission(int $formId, array $answers, string $shareHash = ' * @throws OCSBadRequestException Submission doesn't belong to given form * @throws OCSNotFoundException Could not find form or submission * @throws OCSForbiddenException This form is not owned by the current user and user has no `results_delete` permission + * + * 200: the id of the deleted submission */ #[CORS()] #[NoAdminRequired()] @@ -1328,6 +1366,8 @@ public function deleteSubmission(int $formId, int $submissionId): DataResponse { * @return DataResponse * @throws OCSForbiddenException The current user has no permission to get the results for this form * @throws OCSNotFoundException Could not find form + * + * 200: the file name used for storing the submissions */ #[CORS()] #[NoAdminRequired()] @@ -1365,6 +1405,8 @@ public function exportSubmissionsToCloud(int $formId, string $path, string $file * @throws OCSBadRequestException File type is not allowed * @throws OCSForbiddenException Already submitted * @throws OCSNotFoundException Could not find question + * + * 200: the file id and name of the uploaded file */ #[CORS()] #[NoAdminRequired()] diff --git a/lib/Controller/ShareApiController.php b/lib/Controller/ShareApiController.php index 4fd9d72f0..1249eeacf 100644 --- a/lib/Controller/ShareApiController.php +++ b/lib/Controller/ShareApiController.php @@ -107,6 +107,8 @@ public function __construct( * @throws OCSForbiddenException Link share not allowed * @throws OCSForbiddenException This form is not owned by the current user * @throws OCSNotFoundException Could not find form + * + * 201: the created share */ #[CORS()] #[NoAdminRequired()] @@ -237,6 +239,8 @@ public function newShare(int $formId, int $shareType, string $shareWith = '', ar * @throws OCSForbiddenException Empty keyValuePairs, will not update * @throws OCSForbiddenException Not allowed to update other properties than permissions * @throws OCSNotFoundException Could not find share + * + * 200: the id of the updated share */ #[CORS()] #[NoAdminRequired()] @@ -329,6 +333,8 @@ public function updateShare(int $formId, int $shareId, array $keyValuePairs): Da * @throws OCSBadRequestException Share doesn't belong to given Form * @throws OCSForbiddenException This form is not owned by the current user * @throws OCSNotFoundException Could not find share + * + * 200: the id of the deleted share */ #[CORS()] #[NoAdminRequired()] diff --git a/lib/ResponseDefinitions.php b/lib/ResponseDefinitions.php index 930ca7e5e..c77acd061 100644 --- a/lib/ResponseDefinitions.php +++ b/lib/ResponseDefinitions.php @@ -88,7 +88,7 @@ * submitMultiple: bool, * showExpiration: bool, * canSubmit: bool, - * permissions: array, + * permissions: string[], * questions: array, * state: int, * shares: string[], diff --git a/openapi.json b/openapi.json index a12d8d48c..5e94ba642 100644 --- a/openapi.json +++ b/openapi.json @@ -462,7 +462,7 @@ ], "responses": { "200": { - "description": "", + "description": "Array containing the partial owned or shared forms", "content": { "application/json": { "schema": { @@ -567,7 +567,7 @@ ], "responses": { "201": { - "description": "", + "description": "the created form", "content": { "application/json": { "schema": { @@ -663,7 +663,7 @@ ], "responses": { "200": { - "description": "", + "description": "the requested form", "content": { "application/json": { "schema": { @@ -810,7 +810,7 @@ ], "responses": { "200": { - "description": "", + "description": "the id of the updated form", "content": { "application/json": { "schema": { @@ -830,8 +830,15 @@ "$ref": "#/components/schemas/OCSMeta" }, "data": { - "type": "integer", - "format": "int64" + "oneOf": [ + { + "type": "integer", + "format": "int64" + }, + { + "type": "string" + } + ] } } } @@ -961,7 +968,7 @@ ], "responses": { "200": { - "description": "", + "description": "the id of the deleted form", "content": { "application/json": { "schema": { @@ -1086,7 +1093,7 @@ ], "responses": { "200": { - "description": "", + "description": "the questions of the given form", "content": { "application/json": { "schema": { @@ -1238,7 +1245,7 @@ ], "responses": { "201": { - "description": "", + "description": "the created question", "content": { "application/json": { "schema": { @@ -1411,7 +1418,7 @@ ], "responses": { "200": { - "description": "", + "description": "the question ids of the given form in the new order", "content": { "application/json": { "schema": { @@ -1577,7 +1584,7 @@ ], "responses": { "200": { - "description": "", + "description": "the requested question", "content": { "application/json": { "schema": { @@ -1759,7 +1766,7 @@ ], "responses": { "200": { - "description": "", + "description": "the id of the updated question", "content": { "application/json": { "schema": { @@ -1920,7 +1927,7 @@ ], "responses": { "200": { - "description": "", + "description": "the id of the deleted question", "content": { "application/json": { "schema": { @@ -2105,7 +2112,7 @@ ], "responses": { "201": { - "description": "", + "description": "the created option", "content": { "application/json": { "schema": { @@ -2291,7 +2298,7 @@ ], "responses": { "200": { - "description": "", + "description": "the options of the question in the new order", "content": { "application/json": { "schema": { @@ -2498,7 +2505,7 @@ ], "responses": { "200": { - "description": "", + "description": "the id of the updated option", "content": { "application/json": { "schema": { @@ -2669,7 +2676,7 @@ ], "responses": { "200": { - "description": "", + "description": "the id of the deleted option", "content": { "application/json": { "schema": { @@ -2831,7 +2838,7 @@ ], "responses": { "200": { - "description": "", + "description": "the submissions of the form", "content": { "application/json": { "schema": { @@ -2971,7 +2978,7 @@ ], "responses": { "200": { - "description": "", + "description": "the form id of the deleted submission", "content": { "application/json": { "schema": { @@ -3125,7 +3132,7 @@ ], "responses": { "201": { - "description": "", + "description": "empty response", "content": { "application/json": { "schema": { @@ -3287,7 +3294,7 @@ ], "responses": { "200": { - "description": "", + "description": "the id of the deleted submission", "content": { "application/json": { "schema": { @@ -3464,7 +3471,7 @@ ], "responses": { "200": { - "description": "", + "description": "the file name used for storing the submissions", "content": { "application/json": { "schema": { @@ -3616,7 +3623,7 @@ ], "responses": { "200": { - "description": "", + "description": "the file id and name of the uploaded file", "content": { "application/json": { "schema": { @@ -3801,7 +3808,7 @@ ], "responses": { "201": { - "description": "", + "description": "the created share", "content": { "application/json": { "schema": { @@ -3994,7 +4001,7 @@ ], "responses": { "200": { - "description": "", + "description": "the id of the updated share", "content": { "application/json": { "schema": { @@ -4155,7 +4162,7 @@ ], "responses": { "200": { - "description": "", + "description": "the id of the deleted share", "content": { "application/json": { "schema": {