user_ldap: Add OpenAPI spec

Signed-off-by: jld3103 <jld3103yt@gmail.com>

2 files changed, 410 insertions, 76 deletions

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:
-	 *
-	 * <?xml version="1.0"?>
-	 * <ocs>
-	 *   <meta>
-	 *     <status>ok</status>
-	 *     <statuscode>200</statuscode>
-	 *     <message>OK</message>
-	 *   </meta>
-	 *   <data>
-	 *     <configID>s40</configID>
-	 *   </data>
-	 * </ocs>
-	 *
-	 * Failing example: if an exception is thrown (e.g. Database connection lost)
-	 * the detailed error will be logged. The output will then look like:
-	 *
-	 * <?xml version="1.0"?>
-	 * <ocs>
-	 *   <meta>
-	 *     <status>failure</status>
-	 *     <statuscode>999</statuscode>
-	 *     <message>An issue occurred when creating the new config.</message>
-	 *   </meta>
-	 *   <data/>
-	 * </ocs>
-	 *
-	 * 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<Http::STATUS_OK, array{configID: string}, array{}>
 	 * @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
-	 *
-	 * <?xml version="1.0"?>
-	 * <ocs>
-	 *   <meta>
-	 *     <status>ok</status>
-	 *     <statuscode>200</statuscode>
-	 *     <message>OK</message>
-	 *   </meta>
-	 *   <data/>
-	 * </ocs>
+	 * 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<Http::STATUS_OK, array<empty>, 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
-	 *
-	 * <?xml version="1.0"?>
-	 * <ocs>
-	 *   <meta>
-	 *     <status>ok</status>
-	 *     <statuscode>200</statuscode>
-	 *     <message>OK</message>
-	 *   </meta>
-	 *   <data/>
-	 * </ocs>
+	 * 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<string, mixed> $configData New config
+	 * @return DataResponse<Http::STATUS_OK, array<empty>, 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:
 	 * <?xml version="1.0"?>
 	 * <ocs>
 	 *   <meta>
@@ -285,10 +232,13 @@ class ConfigAPIController extends OCSController {
 	 * </ocs>
 	 *
 	 * @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<Http::STATUS_OK, array<string, mixed>, 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