From c414a7bdf807b3b9059f4f1cb190e4671ec4d9c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=B4me=20Chilliet?= Date: Tue, 7 Oct 2025 10:32:52 +0200 Subject: [PATCH] fix: Fix documentation for controllers and update openapi.json MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Also removed save action from WizardController as there is already a route in ConfigApiController to save a configuration. Signed-off-by: Côme Chilliet Signed-off-by: Louis Chmn --- .../lib/Controller/ConfigAPIController.php | 4 +- .../lib/Controller/WizardController.php | 24 +- apps/user_ldap/openapi.json | 525 ++++++++++++++++++ openapi.json | 525 ++++++++++++++++++ 4 files changed, 1058 insertions(+), 20 deletions(-) diff --git a/apps/user_ldap/lib/Controller/ConfigAPIController.php b/apps/user_ldap/lib/Controller/ConfigAPIController.php index ac5482cb461..ca04e29550c 100644 --- a/apps/user_ldap/lib/Controller/ConfigAPIController.php +++ b/apps/user_ldap/lib/Controller/ConfigAPIController.php @@ -236,6 +236,7 @@ class ConfigAPIController extends OCSController { /** * Test a configuration * + * @param string $configID ID of the LDAP config * @return DataResponse * @throws OCSException An unexpected error happened * @throws OCSNotFoundException Config not found @@ -303,11 +304,12 @@ class ConfigAPIController extends OCSController { /** * Copy a configuration * + * @param string $configID ID of the LDAP config * @return DataResponse * @throws OCSException An unexpected error happened * @throws OCSNotFoundException Config not found * - * 200: Test was run and results are returned + * 200: Config was copied, new configID was returned */ #[AuthorizedAdminSetting(settings: Admin::class)] #[ApiRoute(verb: 'POST', url: '/api/v1/config/{configID}/copy')] diff --git a/apps/user_ldap/lib/Controller/WizardController.php b/apps/user_ldap/lib/Controller/WizardController.php index 302ab95b7ed..afc59098399 100644 --- a/apps/user_ldap/lib/Controller/WizardController.php +++ b/apps/user_ldap/lib/Controller/WizardController.php @@ -38,7 +38,10 @@ class WizardController extends OCSController { /** * Run a wizard action and returns the result * - * @return DataResponse + * @param string $configID ID of the LDAP configuration + * @param string $wizardAction Wizard action to run + * @param ?string $loginName Login name to test for testLoginName action + * @return DataResponse|list>,options?:array>}, array{}> * @throws OCSException * * 200: Wizard action result @@ -47,7 +50,7 @@ class WizardController extends OCSController { #[ApiRoute(verb: 'POST', url: '/api/v1/wizard/{configID}/{wizardAction}')] public function action( string $configID, string $wizardAction, - ?string $loginName = null, ?string $key = null, ?string $val = null, + ?string $loginName = null, ) { try { $wizard = $this->wizardFactory->get($configID); @@ -92,23 +95,6 @@ class WizardController extends OCSController { } throw new OCSException(); - case 'save': - if ($key === null || $val === null) { - throw new OCSException($this->l->t('No data specified')); - exit; - } - $setParameters = []; - $configuration = new Configuration($configID); - $configuration->setConfiguration([$key => $val], $setParameters); - if (!in_array($key, $setParameters)) { - throw new OCSException($this->l->t('Could not set configuration %1$s to %2$s', [$key, $setParameters[0]])); - } - $configuration->saveConfiguration(); - //clear the cache on save - $connection = $this->connectionFactory->get($configID); - $connection->clearCache(); - return new DataResponse(); - break; default: throw new OCSException($this->l->t('Action does not exist')); break; diff --git a/apps/user_ldap/openapi.json b/apps/user_ldap/openapi.json index 7a04c35072e..d3e890137da 100644 --- a/apps/user_ldap/openapi.json +++ b/apps/user_ldap/openapi.json @@ -696,6 +696,531 @@ } } } + }, + "/ocs/v2.php/apps/user_ldap/api/v1/config/{configID}/test": { + "post": { + "operationId": "configapi-test-configuration", + "summary": "Test a configuration", + "description": "This endpoint requires admin access", + "tags": [ + "configapi" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "configID", + "in": "path", + "description": "ID of the LDAP config", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "Test was run and results are 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": [ + "success", + "message" + ], + "properties": { + "success": { + "type": "boolean" + }, + "message": { + "type": "string" + } + } + } + } + } + } + } + } + } + }, + "404": { + "description": "Config not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "401": { + "description": "Current user is not logged in", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "403": { + "description": "Logged in account must be an admin", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/user_ldap/api/v1/config/{configID}/copy": { + "post": { + "operationId": "configapi-copy-configuration", + "summary": "Copy a configuration", + "description": "This endpoint requires admin access", + "tags": [ + "configapi" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "configID", + "in": "path", + "description": "ID of the LDAP config", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "Config was copied, new configID was 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": [ + "configID" + ], + "properties": { + "configID": { + "type": "string" + } + } + } + } + } + } + } + } + } + }, + "404": { + "description": "Config not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "401": { + "description": "Current user is not logged in", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "403": { + "description": "Logged in account must be an admin", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/user_ldap/api/v1/wizard/{configID}/{wizardAction}": { + "post": { + "operationId": "wizard-action", + "summary": "Run a wizard action and returns the result", + "description": "This endpoint requires admin access", + "tags": [ + "wizard" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "loginName": { + "type": "string", + "nullable": true, + "default": null, + "description": "Login name to test for testLoginName action" + } + } + } + } + } + }, + "parameters": [ + { + "name": "configID", + "in": "path", + "description": "ID of the LDAP configuration", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "wizardAction", + "in": "path", + "description": "Wizard action to run", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "Wizard action result", + "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": [ + "changes" + ], + "properties": { + "changes": { + "type": "object", + "additionalProperties": { + "anyOf": [ + { + "type": "integer", + "format": "int64" + }, + { + "type": "string" + }, + { + "type": "array", + "items": { + "type": "integer", + "format": "int64" + } + }, + { + "type": "array", + "items": { + "type": "string" + } + } + ] + } + }, + "options": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + } + } + } + } + } + }, + "401": { + "description": "Current user is not logged in", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "403": { + "description": "Logged in account must be an admin", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } } }, "tags": [] diff --git a/openapi.json b/openapi.json index e0c9d77d2e8..2f20c16788e 100644 --- a/openapi.json +++ b/openapi.json @@ -35382,6 +35382,531 @@ } } }, + "/ocs/v2.php/apps/user_ldap/api/v1/config/{configID}/test": { + "post": { + "operationId": "user_ldap-configapi-test-configuration", + "summary": "Test a configuration", + "description": "This endpoint requires admin access", + "tags": [ + "user_ldap/configapi" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "configID", + "in": "path", + "description": "ID of the LDAP config", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "Test was run and results are 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": [ + "success", + "message" + ], + "properties": { + "success": { + "type": "boolean" + }, + "message": { + "type": "string" + } + } + } + } + } + } + } + } + } + }, + "404": { + "description": "Config not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "401": { + "description": "Current user is not logged in", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "403": { + "description": "Logged in account must be an admin", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/user_ldap/api/v1/config/{configID}/copy": { + "post": { + "operationId": "user_ldap-configapi-copy-configuration", + "summary": "Copy a configuration", + "description": "This endpoint requires admin access", + "tags": [ + "user_ldap/configapi" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "configID", + "in": "path", + "description": "ID of the LDAP config", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "Config was copied, new configID was 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": [ + "configID" + ], + "properties": { + "configID": { + "type": "string" + } + } + } + } + } + } + } + } + } + }, + "404": { + "description": "Config not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "401": { + "description": "Current user is not logged in", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "403": { + "description": "Logged in account must be an admin", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/user_ldap/api/v1/wizard/{configID}/{wizardAction}": { + "post": { + "operationId": "user_ldap-wizard-action", + "summary": "Run a wizard action and returns the result", + "description": "This endpoint requires admin access", + "tags": [ + "user_ldap/wizard" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "loginName": { + "type": "string", + "nullable": true, + "default": null, + "description": "Login name to test for testLoginName action" + } + } + } + } + } + }, + "parameters": [ + { + "name": "configID", + "in": "path", + "description": "ID of the LDAP configuration", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "wizardAction", + "in": "path", + "description": "Wizard action to run", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "description": "Required to be true for the API request to pass", + "required": true, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "Wizard action result", + "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": [ + "changes" + ], + "properties": { + "changes": { + "type": "object", + "additionalProperties": { + "anyOf": [ + { + "type": "integer", + "format": "int64" + }, + { + "type": "string" + }, + { + "type": "array", + "items": { + "type": "integer", + "format": "int64" + } + }, + { + "type": "array", + "items": { + "type": "string" + } + } + ] + } + }, + "options": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + } + } + } + } + } + }, + "401": { + "description": "Current user is not logged in", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "403": { + "description": "Logged in account must be an admin", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, "/ocs/v2.php/apps/user_status/api/v1/heartbeat": { "put": { "operationId": "user_status-heartbeat-heartbeat",