From a95bebde348f1146ca1ae3103123a04aa5347b62 Mon Sep 17 00:00:00 2001 From: jld3103 Date: Mon, 21 Aug 2023 05:45:43 +0200 Subject: [PATCH] files_reminders: Add OpenAPI spec Signed-off-by: jld3103 --- .../lib/Controller/ApiController.php | 23 + apps/files_reminders/openapi.json | 495 ++++++++++++++++++ 2 files changed, 518 insertions(+) create mode 100644 apps/files_reminders/openapi.json diff --git a/apps/files_reminders/lib/Controller/ApiController.php b/apps/files_reminders/lib/Controller/ApiController.php index ed23ee032ba..91b7e51eb6f 100644 --- a/apps/files_reminders/lib/Controller/ApiController.php +++ b/apps/files_reminders/lib/Controller/ApiController.php @@ -54,6 +54,12 @@ class ApiController extends OCSController { /** * Get a reminder + * + * @param int $fileId ID of the file + * @return DataResponse|DataResponse, array{}> + * + * 200: Reminder returned + * 401: User not found */ #[NoAdminRequired] public function get(int $fileId): DataResponse { @@ -79,7 +85,16 @@ class ApiController extends OCSController { /** * Set a reminder * + * @param int $fileId ID of the file * @param string $dueDate ISO 8601 formatted date time string + * + * @return DataResponse, array{}> + * + * 200: Reminder updated + * 201: Reminder created successfully + * 400: Creating reminder is not possible + * 401: User not found + * 404: File not found */ #[NoAdminRequired] public function set(int $fileId, string $dueDate): DataResponse { @@ -108,6 +123,14 @@ class ApiController extends OCSController { /** * Remove a reminder + * + * @param int $fileId ID of the file + * + * @return DataResponse, array{}> + * + * 200: Reminder deleted successfully + * 401: User not found + * 404: Reminder not found */ #[NoAdminRequired] public function remove(int $fileId): DataResponse { diff --git a/apps/files_reminders/openapi.json b/apps/files_reminders/openapi.json new file mode 100644 index 00000000000..2baa4e1bdb9 --- /dev/null +++ b/apps/files_reminders/openapi.json @@ -0,0 +1,495 @@ +{ + "openapi": "3.0.3", + "info": { + "title": "files_reminders", + "version": "0.0.1", + "description": "Set file reminders", + "license": { + "name": "agpl" + } + }, + "components": { + "securitySchemes": { + "basic_auth": { + "type": "http", + "scheme": "basic" + }, + "bearer_auth": { + "type": "http", + "scheme": "bearer" + } + }, + "schemas": { + "OCSMeta": { + "type": "object", + "required": [ + "status", + "statuscode" + ], + "properties": { + "status": { + "type": "string" + }, + "statuscode": { + "type": "integer" + }, + "message": { + "type": "string" + }, + "totalitems": { + "type": "string" + }, + "itemsperpage": { + "type": "string" + } + } + } + } + }, + "paths": { + "/ocs/v2.php/apps/files_reminders/api/v{version}/{fileId}": { + "get": { + "operationId": "api-get", + "summary": "Get a reminder", + "tags": [ + "api" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "version", + "in": "path", + "required": true, + "schema": { + "type": "string", + "pattern": "^1$" + } + }, + { + "name": "fileId", + "in": "path", + "description": "ID of the file", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "Reminder returned", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "object", + "required": [ + "dueDate" + ], + "properties": { + "dueDate": { + "type": "string", + "nullable": true + } + } + } + } + } + } + } + } + } + }, + "401": { + "description": "User not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + }, + "put": { + "operationId": "api-set", + "summary": "Set a reminder", + "tags": [ + "api" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "dueDate", + "in": "query", + "description": "ISO 8601 formatted date time string", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "version", + "in": "path", + "required": true, + "schema": { + "type": "string", + "pattern": "^1$" + } + }, + { + "name": "fileId", + "in": "path", + "description": "ID of the file", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "Reminder updated", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "201": { + "description": "Reminder created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "400": { + "description": "Creating reminder is not possible", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "401": { + "description": "User not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "404": { + "description": "File not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + }, + "delete": { + "operationId": "api-remove", + "summary": "Remove a reminder", + "tags": [ + "api" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "version", + "in": "path", + "required": true, + "schema": { + "type": "string", + "pattern": "^1$" + } + }, + { + "name": "fileId", + "in": "path", + "description": "ID of the file", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "Reminder deleted successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "401": { + "description": "User not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "404": { + "description": "Reminder not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + } + }, + "tags": [] +} \ No newline at end of file -- 2.39.5