From 61a13bed4d8536ac88eff08db4e8bfe8b62305fd Mon Sep 17 00:00:00 2001 From: jld3103 Date: Wed, 14 Jun 2023 17:20:21 +0200 Subject: [PATCH] user_ldap: Add OpenAPI spec Signed-off-by: jld3103 --- .../lib/Controller/ConfigAPIController.php | 102 ++--- apps/user_ldap/openapi.json | 384 ++++++++++++++++++ 2 files changed, 410 insertions(+), 76 deletions(-) create mode 100644 apps/user_ldap/openapi.json diff --git a/apps/user_ldap/lib/Controller/ConfigAPIController.php b/apps/user_ldap/lib/Controller/ConfigAPIController.php index e408d03fcd5..23c35895c94 100644 --- a/apps/user_ldap/lib/Controller/ConfigAPIController.php +++ b/apps/user_ldap/lib/Controller/ConfigAPIController.php @@ -29,6 +29,7 @@ use OC\Security\IdentityProof\Manager; use OCA\User_LDAP\Configuration; use OCA\User_LDAP\ConnectionFactory; use OCA\User_LDAP\Helper; +use OCP\AppFramework\Http; use OCP\AppFramework\Http\DataResponse; use OCP\AppFramework\OCS\OCSBadRequestException; use OCP\AppFramework\OCS\OCSException; @@ -76,42 +77,10 @@ class ConfigAPIController extends OCSController { } /** - * Creates a new (empty) configuration and returns the resulting prefix - * - * Example: curl -X POST -H "OCS-APIREQUEST: true" -u $admin:$password \ - * https://nextcloud.server/ocs/v2.php/apps/user_ldap/api/v1/config - * - * results in: - * - * - * - * - * ok - * 200 - * OK - * - * - * s40 - * - * - * - * Failing example: if an exception is thrown (e.g. Database connection lost) - * the detailed error will be logged. The output will then look like: - * - * - * - * - * failure - * 999 - * An issue occurred when creating the new config. - * - * - * - * - * For JSON output provide the format=json parameter + * Create a new (empty) configuration and return the resulting prefix * * @AuthorizedAdminSetting(settings=OCA\User_LDAP\Settings\Admin) - * @return DataResponse + * @return DataResponse * @throws OCSException */ public function create() { @@ -128,27 +97,15 @@ class ConfigAPIController extends OCSController { } /** - * Deletes a LDAP configuration, if present. - * - * Example: - * curl -X DELETE -H "OCS-APIREQUEST: true" -u $admin:$password \ - * https://nextcloud.server/ocs/v2.php/apps/user_ldap/api/v1/config/s60 - * - * - * - * - * ok - * 200 - * OK - * - * - * + * Delete a LDAP configuration * * @AuthorizedAdminSetting(settings=OCA\User_LDAP\Settings\Admin) - * @param string $configID - * @return DataResponse - * @throws OCSBadRequestException + * @param string $configID ID of the config + * @return DataResponse, array{}> * @throws OCSException + * @throws OCSNotFoundException Config not found + * + * 200: Config deleted successfully */ public function delete($configID) { try { @@ -167,28 +124,17 @@ class ConfigAPIController extends OCSController { } /** - * Modifies a configuration - * - * Example: - * curl -X PUT -d "configData[ldapHost]=ldaps://my.ldap.server&configData[ldapPort]=636" \ - * -H "OCS-APIREQUEST: true" -u $admin:$password \ - * https://nextcloud.server/ocs/v2.php/apps/user_ldap/api/v1/config/s60 - * - * - * - * - * ok - * 200 - * OK - * - * - * + * Modify a configuration * * @AuthorizedAdminSetting(settings=OCA\User_LDAP\Settings\Admin) - * @param string $configID - * @param array $configData - * @return DataResponse + * @param string $configID ID of the config + * @param array $configData New config + * @return DataResponse, array{}> * @throws OCSException + * @throws OCSBadRequestException Modifying config is not possible + * @throws OCSNotFoundException Config not found + * + * 200: Config returned */ public function modify($configID, $configData) { try { @@ -220,8 +166,9 @@ class ConfigAPIController extends OCSController { } /** - * Retrieves a configuration + * Get a configuration * + * Output can look like this: * * * @@ -285,10 +232,13 @@ class ConfigAPIController extends OCSController { * * * @AuthorizedAdminSetting(settings=OCA\User_LDAP\Settings\Admin) - * @param string $configID - * @param bool|string $showPassword - * @return DataResponse + * @param string $configID ID of the config + * @param bool $showPassword Whether to show the password + * @return DataResponse, array{}> * @throws OCSException + * @throws OCSNotFoundException Config not found + * + * 200: Config returned */ public function show($configID, $showPassword = false) { try { @@ -296,7 +246,7 @@ class ConfigAPIController extends OCSController { $config = new Configuration($configID); $data = $config->getConfiguration(); - if (!(int)$showPassword) { + if (!$showPassword) { $data['ldapAgentPassword'] = '***'; } foreach ($data as $key => $value) { diff --git a/apps/user_ldap/openapi.json b/apps/user_ldap/openapi.json new file mode 100644 index 00000000000..5be4938e177 --- /dev/null +++ b/apps/user_ldap/openapi.json @@ -0,0 +1,384 @@ +{ + "openapi": "3.0.3", + "info": { + "title": "user_ldap", + "version": "0.0.1", + "description": "This application enables administrators to connect Nextcloud to an LDAP-based user directory.", + "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/user_ldap/api/v1/config": { + "post": { + "operationId": "configapi-create", + "summary": "Create a new (empty) configuration and return the resulting prefix", + "description": "This endpoint requires admin access", + "tags": [ + "configapi" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "", + "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" + } + } + } + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/user_ldap/api/v1/config/{configID}": { + "get": { + "operationId": "configapi-show", + "summary": "Get a configuration", + "description": "This endpoint requires admin access", + "tags": [ + "configapi" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "showPassword", + "in": "query", + "description": "Whether to show the password", + "schema": { + "type": "integer", + "default": 0 + } + }, + { + "name": "configID", + "in": "path", + "description": "ID of the config", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "Config 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", + "additionalProperties": { + "type": "object" + } + } + } + } + } + } + } + } + }, + "404": { + "description": "Config not found", + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + } + } + } + }, + "put": { + "operationId": "configapi-modify", + "summary": "Modify a configuration", + "description": "This endpoint requires admin access", + "tags": [ + "configapi" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "configData", + "in": "query", + "description": "New config", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "configID", + "in": "path", + "description": "ID of the config", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "Config returned", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "400": { + "description": "Modifying config is not possible", + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + } + }, + "404": { + "description": "Config not found", + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + } + } + } + }, + "delete": { + "operationId": "configapi-delete", + "summary": "Delete a LDAP configuration", + "description": "This endpoint requires admin access", + "tags": [ + "configapi" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "configID", + "in": "path", + "description": "ID of the config", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "Config deleted successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "404": { + "description": "Config not found", + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + } + } + } + } + } + }, + "tags": [] +} \ No newline at end of file -- 2.39.5