fixed docs for app-cfg and preferences-cfg (#167)

nextcloud · Dec 18, 2023 · d4610dc · d4610dc
1 parent 253fd43
commit d4610dc
Show file tree

Hide file tree

Showing 4 changed files with 146 additions and 64 deletions.
diff --git a/docs/tech_details/api/appconfig.rst b/docs/tech_details/api/appconfig.rst
@@ -7,7 +7,9 @@ ExApp AppConfig API is similar to the standard Nextcloud **appconfig** API.
 Set app config value
 ^^^^^^^^^^^^^^^^^^^^
 
-Set ExApp config value.
+Set or update ExApp config value.
+
+.. note:: when ``sensitive`` is not specified during updating value, it will be not changed to default.
 
 OCS endpoint: ``POST /apps/app_api/api/v1/ex-app/config``
 
@@ -17,38 +19,39 @@ Request data
 .. code-block:: json
 
  {
- "key": "key",
- "value": "value"
- "sensitive": "sensitive flag affecting the visibility of the value (true/false, default: false)"
+ "configKey": "key",
+ "configValue": "value"
+ "sensitive": "sensitive flag affecting the visibility of the value (0/1, default: 0)"
  }
 
 Response data
 *************
 
 On success, ExAppConfig object is returned.
+On error OCS Bad Request is returned.
 
 .. code-block:: json
 
  {
- "key": "key",
- "value": "value"
- "sensitive": "true/false"
- }
-
-Update app config value or sensitive flag
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Update existing ExApp config value or sensitive flag.
-It's the same endpoint as for setting config value.
-
-OCS endpoint: ``POST /apps/app_api/api/v1/ex-app/config``
-
-.. code-block:: json
-
- {
- "key": "key",
- "value": "value"
- "sensitive": "(optional), will not be updated if not provided"
+ "ocs":
+ {
+  "meta":
+  {
+ "status":"ok",
+ "statuscode":100,
+ "message":"OK",
+ "totalitems":"",
+ "itemsperpage":""
+ },
+ "data":
+ {
+ "id":1084,
+ "appid":"app_id",
+ "configkey":"key",
+  "configvalue":"value",
+  "sensitive":1
+  }
+ }
  }
 
 Get app config values
@@ -74,11 +77,25 @@ List of ExApp config values are returned.
 
 .. code-block:: json
 
- [
- { "configkey": "key1", "configvalue": "value1" },
- { "configkey": "key2", "configvalue": "value2" },
- { "configkey": "key3", "configvalue": "value3" },
- ]
+ {
+ "ocs":
+ {
+ "meta":
+ {
+ "status":"ok",
+ "statuscode":100,
+ "message":"OK",
+ "totalitems":"",
+ "itemsperpage":""
+ },
+ "data":[
+ {
+ "configkey":"test_key",
+ "configvalue":"123"
+ }
+ ]
+ }
+ }
 
 Delete app config values
 ^^^^^^^^^^^^^^^^^^^^^^^^
@@ -100,3 +117,20 @@ Response
 ********
 
 Returns the number of configuration values removed.
+
+.. code-block:: json
+
+ {
+ "ocs":
+ {
+ "meta":
+ {
+ "status":"ok",
+ "statuscode":100,
+ "message":"OK",
+ "totalitems":"",
+ "itemsperpage":""
+ },
+ "data":1
+ }
+ }
diff --git a/docs/tech_details/api/preferences.rst b/docs/tech_details/api/preferences.rst
@@ -9,13 +9,13 @@ It's a user specific settings.
 Set user config value
 ^^^^^^^^^^^^^^^^^^^^^
 
+Set or update config value for **current authenticated user**.
+
 OCS endpoint: ``POST /apps/app_api/api/v1/ex-app/preference``
 
 Request data
 ************
 
-Set config value for **current authenticated user**.
-
 .. code-block:: json
 
  {
@@ -27,35 +27,90 @@ Response data
 *************
 
 On success ExAppPreference object is returned.
-If config value is not set - ``null`` is returned.
+On error OCS Bad Request is returned.
 
+.. code-block:: json
+
+ {
+ "ocs":
+ {
+ "meta":
+ {
+ "status":"ok",
+ "statuscode":100,
+ "message":"OK",
+ "totalitems":"",
+ "itemsperpage":""
+ },
+ "data":
+ {
+ "id":983,
+ "appid":"app_id",
+ "configkey":"test key",
+ "configvalue":"123",
+ "sensitive":0
+ }
+ }
+ }
 
 Get user config values
 ^^^^^^^^^^^^^^^^^^^^^^
 
+Get config values for **current authenticated user**.
+
 OCS endpoint: ``POST /apps/app_api/api/v1/ex-app/preference/get-values``
 
 Request data
 ************
 
-Get config values for **current authenticated user**.
-
 .. code-block:: json
 
  {
  "configKeys": ["key1", "key2", "key3"]
  }
 
+Response data
+*************
+
+List of ExApp preferences values are returned.
+
+.. code-block:: json
+
+ {
+ "ocs":
+ {
+ "meta":
+ {
+ "status":"ok",
+ "statuscode":100,
+ "message":"OK",
+ "totalitems":"",
+ "itemsperpage":""
+ },
+ "data":[
+ {
+ "configkey":"test key",
+ "configvalue":"123"
+ },
+ {
+ "configkey":"test key2",
+ "configvalue":"321"
+ }
+ ]
+ }
+ }
+
+
 Delete user config values
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
+Delete config values for **current authenticated user**.
+
 OCS endpoint: ``DELETE /apps/app_api/api/v1/ex-app/preference``
 
 Request data
 ************
 
-Delete config values for **current authenticated user**.
-
 .. code-block:: json
 
  {
@@ -65,4 +120,19 @@ Delete config values for **current authenticated user**.
 Response
 ********
 
-Returns the number of configuration values removed.
+.. code-block:: json
+
+ {
+ "ocs":
+ {
+ "meta":
+ {
+ "status":"ok",
+ "statuscode":100,
+ "message":"OK",
+ "totalitems":"",
+ "itemsperpage":""
+ },
+ "data":2
+ }
+ }
diff --git a/lib/Controller/AppConfigController.php b/lib/Controller/AppConfigController.php
@@ -22,8 +22,8 @@ class AppConfigController extends OCSController {
  protected $request;
 
  public function __construct(
- IRequest $request,
- private ExAppConfigService $exAppConfigService,
+ IRequest  $request,
+ private readonly ExAppConfigService $exAppConfigService,
  ) {
  parent::__construct(Application::APP_ID, $request);
 
@@ -34,11 +34,7 @@ public function __construct(
  * @PublicPage
  * @NoCSRFRequired
  *
- * @param string $configKey
- * @param mixed $configValue
- * @param int|null $sensitive
  * @throws OCSBadRequestException
- * @return DataResponse
  */
  #[AppAPIAuth]
  #[PublicPage]
@@ -58,10 +54,6 @@ public function setAppConfigValue(string $configKey, mixed $configValue, ?int $s
  /**
  * @PublicPage
  * @NoCSRFRequired
- *
- * @param array $configKeys
- *
- * @return DataResponse
  */
  #[AppAPIAuth]
  #[PublicPage]
@@ -76,11 +68,8 @@ public function getAppConfigValues(array $configKeys): DataResponse {
  * @PublicPage
  * @NoCSRFRequired
  *
- * @param array $configKeys
- *
  * @throws OCSBadRequestException
  * @throws OCSNotFoundException
- * @return DataResponse
  */
  #[AppAPIAuth]
  #[PublicPage]

diff --git a/lib/Controller/PreferencesController.php b/lib/Controller/PreferencesController.php
@@ -23,9 +23,9 @@ class PreferencesController extends OCSController {
  protected $request;
 
  public function __construct(
- IRequest $request,
- private IUserSession $userSession,
- private ExAppPreferenceService $exAppPreferenceService,
+ IRequest  $request,
+ private readonly IUserSession  $userSession,
+ private readonly ExAppPreferenceService $exAppPreferenceService,
  ) {
  parent::__construct(Application::APP_ID, $request);
 
@@ -36,11 +36,7 @@ public function __construct(
  * @PublicPage
  * @NoCSRFRequired
  *
- * @param string $configKey
- * @param mixed $configValue
- *
  * @throws OCSBadRequestException
- * @return DataResponse
  */
  #[AppAPIAuth]
  #[PublicPage]
@@ -53,18 +49,14 @@ public function setUserConfigValue(string $configKey, mixed $configValue): DataR
  $appId = $this->request->getHeader('EX-APP-ID');
  $result = $this->exAppPreferenceService->setUserConfigValue($userId, $appId, $configKey, $configValue);
  if ($result instanceof ExAppPreference) {
- return new DataResponse(1, Http::STATUS_OK);
+ return new DataResponse($result, Http::STATUS_OK);
  }
  throw new OCSBadRequestException('Failed to set user config value');
  }
 
  /**
  * @PublicPage
  * @NoCSRFRequired
- *
- * @param array $configKeys
- *
- * @return DataResponse
  */
  #[AppAPIAuth]
  #[PublicPage]
@@ -80,11 +72,8 @@ public function getUserConfigValues(array $configKeys): DataResponse {
  * @PublicPage
  * @NoCSRFRequired
  *
- * @param array $configKeys
- *
  * @throws OCSBadRequestException
  * @throws OCSNotFoundException
- * @return DataResponse
  */
  #[AppAPIAuth]
  #[PublicPage]