feat: Add OpenAPI

Signed-off-by: provokateurin <kate@provokateurin.de>

.eslintrc.js

@@ -6,4 +6,15 @@ module.exports = {
 	extends: [
 		'@nextcloud/eslint-config/typescript',
 	],
+	overrides: [
+		{
+			files: ['src/types/openapi/*.ts'],
+			rules: {
+				'@typescript-eslint/no-explicit-any': 'off',
+				quotes: 'off',
+				'no-multiple-empty-lines': 'off',
+				'no-use-before-define': 'off',
+			},
+		},
+	],
 }

.github/workflows/openapi.yml

@@ -0,0 +1,94 @@
+# This workflow is provided via the organization template repository
+#
+# https://github.com/nextcloud/.github
+# https://docs.github.com/en/actions/learn-github-actions/sharing-workflows-with-your-organization
+#
+# SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+# SPDX-FileCopyrightText: 2024 Arthur Schiwon <blizzz@arthur-schiwon.de>
+# SPDX-License-Identifier: MIT
+
+name: OpenAPI
+
+on: pull_request
+
+permissions:
+  contents: read
+
+concurrency:
+  group: openapi-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  openapi:
+    runs-on: ubuntu-latest
+
+    if: ${{ github.repository_owner != 'nextcloud-gmbh' }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+
+      - name: Get php version
+        id: php_versions
+        uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.3.1
+
+      - name: Set up php
+        uses: shivammathur/setup-php@c541c155eee45413f5b09a52248675b1a2575231 # v2.31.1
+        with:
+          php-version: ${{ steps.php_versions.outputs.php-available }}
+          extensions: xml
+          coverage: none
+          ini-file: development
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Check Typescript OpenApi types
+        id: check_typescript_openapi
+        uses: andstor/file-existence-action@076e0072799f4942c8bc574a82233e1e4d13e9d6 # v3.0.0
+        with:
+          files: "src/types/openapi/openapi*.ts"
+
+      - name: Read package.json node and npm engines version
+        if: steps.check_typescript_openapi.outputs.files_exists == 'true'
+        uses: skjnldsv/read-package-engines-version-actions@06d6baf7d8f41934ab630e97d9e6c0bc9c9ac5e4 # v3
+        id: node_versions
+        # Continue if no package.json
+        continue-on-error: true
+        with:
+          fallbackNode: '^20'
+          fallbackNpm: '^10'
+
+      - name: Set up node ${{ steps.node_versions.outputs.nodeVersion }}
+        if: ${{ steps.node_versions.outputs.nodeVersion }}
+        uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3
+        with:
+          node-version: ${{ steps.node_versions.outputs.nodeVersion }}
+
+      - name: Set up npm ${{ steps.node_versions.outputs.npmVersion }}
+        if: ${{ steps.node_versions.outputs.nodeVersion }}
+        run: npm i -g 'npm@${{ steps.node_versions.outputs.npmVersion }}'
+
+      - name: Install dependencies & build
+        if: ${{ steps.node_versions.outputs.nodeVersion }}
+        env:
+          CYPRESS_INSTALL_BINARY: 0
+          PUPPETEER_SKIP_DOWNLOAD: true
+        run: |
+          npm ci
+
+      - name: Set up dependencies
+        run: composer i
+
+      - name: Regenerate OpenAPI
+        run: composer run openapi
+
+      - name: Check openapi*.json and typescript changes
+        run: |
+          bash -c "[[ ! \"`git status --porcelain `\" ]] || (echo 'Please run \"composer run openapi\" and commit the openapi*.json files and (if applicable) src/types/openapi/openapi*.ts, see the section \"Show changes on failure\" for details' && exit 1)"
+
+      - name: Show changes on failure
+        if: failure()
+        run: |
+          git status
+          git --no-pager diff
+          exit 1 # make it red to grab attention

README.md

@@ -126,35 +126,7 @@ To disable the advanced permissions feature for a group folder, use `occ groupfo
 
 ### REST API
 
-Group folders can be configured externally through REST APIs.
-
-The following REST API's are supported:
-
-- `GET apps/groupfolders/folders`: Returns a list of all configured folders and their settings
-- `POST apps/groupfolders/folders`: Create a new group folder
-    - `mountpoint`: The name for the new folder
-- `GET apps/groupfolders/folders/$folderId`: Return a specific configured folder and its settings
-- `DELETE apps/groupfolders/folders/$folderId`: Delete a group folder
-- `POST apps/groupfolders/folders/$folderId/groups`: Give a group access to a folder
-    - `group`: The id of the group to be given access to the folder
-- `DELETE apps/groupfolders/folders/$folderId/groups/$groupId`: Remove access from a group to a folder
-- `POST apps/groupfolders/folders/$folderId/acl`: Enable/Disable folder advanced permissions
-    - `acl` 1 for enable, 0 for disable.
-- `POST apps/groupfolders/folders/$folderId/manageACL`: Grants/Removes a group or user the ability to manage a groupfolders' advanced permissions
-    - `$mappingId`: the id of the group/user to be granted/removed access to/from the folder
-    - `$mappingType`: 'group' or 'user'
-    - `$manageAcl`: true to grants ability to manage a groupfolders' advanced permissions, false to remove
-- `POST apps/groupfolders/folders/$folderId/groups/$groupId`: Set the permissions a group has in a folder
-    - `permissions` The new permissions for the group as bitmask of [permissions constants](https://github.com/nextcloud/server/blob/b4f36d44c43aac0efdc6c70ff8e46473341a9bfe/lib/public/Constants.php#L65)
-- `POST apps/groupfolders/folders/$folderId/quota`: Set the quota for a folder
-    - `quota`: The new quota for the folder in bytes, user `-3` for unlimited
-- `POST apps/groupfolders/folders/$folderId/mountpoint`: Change the name of a folder
-    - `mountpoint`: The new name for the folder
-
-For all `POST` calls the required parameters are listed.
-
-Non-admins can access the `GET` requests to retrieve info about group folders they have access to.
-Admins can add `applicable=1` as a parameter to the group folder list request to get the same filtered results of only folders they have direct access to.
+See the [OpenAPI specification](openapi.json) to learn about all available API endpoints: https://petstore.swagger.io/?url=https://raw.githubusercontent.com/nextcloud/groupfolders/master/openapi.json
 
 ### WebDAV API
 

REUSE.toml

@@ -35,6 +35,12 @@ precedence = "aggregate"
 SPDX-FileCopyrightText = "2019 Nextcloud GmbH and Nextcloud contributors"
 SPDX-License-Identifier = "AGPL-3.0-or-later"
 
+[[annotations]]
+path = ["vendor-bin/**"]
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2024 Nextcloud GmbH and Nextcloud contributors"
+SPDX-License-Identifier = "AGPL-3.0-or-later"
+
 [[annotations]]
 path = ["cypress/tsconfig.json", "cypress/fixtures/example.json", "screenshots/acl.png", "screenshots/aclAdmin.png", "screenshots/edit.png", "screenshots/folders.png", "screenshots/permissions.png"]
 precedence = "aggregate"
@@ -46,3 +52,9 @@ path = ["img/app-dark.svg", "img/app.svg", "img/deny.svg", "img/folder-group.svg
 precedence = "aggregate"
 SPDX-FileCopyrightText = "2018-2024 Google LLC"
 SPDX-License-Identifier = "Apache-2.0"
+
+[[annotations]]
+path = ["openapi.json", "src/types/openapi/openapi.ts"]
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2024 Nextcloud GmbH and Nextcloud contributors"
+SPDX-License-Identifier = "AGPL-3.0-or-later"

composer.json

@@ -27,7 +27,8 @@
 		"psalm:update-baseline": "psalm.phar --threads=1 --update-baseline",
 		"psalm:clear": "psalm.phar --clear-cache && psalm.phar --clear-global-cache",
 		"psalm:fix": "psalm.phar --alter --issues=InvalidReturnType,InvalidNullableReturnType,MissingParamType,InvalidFalsableReturnType",
-		"test:unit": "vendor/bin/phpunit -c tests/phpunit.xml"
+		"test:unit": "vendor/bin/phpunit -c tests/phpunit.xml",
+		"openapi": "generate-spec && npm run typescript:generate"
 	},
 	"config": {
 		"allow-plugins": {

lib/AppInfo/Capabilities.php

@@ -8,10 +8,10 @@
 namespace OCA\GroupFolders\AppInfo;
 
 use OCA\GroupFolders\Folder\FolderManager;
+use OCP\App\IAppManager;
 use OCP\Capabilities\ICapability;
 use OCP\IUser;
 use OCP\IUserSession;
-use OCP\App\IAppManager;
 
 class Capabilities implements ICapability {
 	private IUserSession $userSession;
@@ -24,6 +24,14 @@ public function __construct(IUserSession $userSession, FolderManager $folderMana
 		$this->appManager = $appManager;
 	}
 
+	/**
+	 * @return array{
+	 *     groupfolders?: array{
+	 *         appVersion: string,
+	 *         hasGroupFolders: bool,
+	 *     },
+	 * }
+	 */
 	public function getCapabilities(): array {
 		$user = $this->userSession->getUser();
 		if (!$user) {

lib/Command/FolderCommand.php

@@ -17,6 +17,8 @@
 
 /**
  * Base command for commands asking the user for a folder id.
+ *
+ * @psalm-import-type InternalFolderOut from FolderManager
  */
 abstract class FolderCommand extends Base {
 	protected FolderManager $folderManager;
@@ -31,7 +33,7 @@ public function __construct(FolderManager $folderManager, IRootFolder $rootFolde
 	}
 
 	/**
-	 * @psalm-return array{id: mixed, mount_point: string, groups: array<empty, empty>|mixed, quota: int, size: int|mixed, acl: bool}|false
+	 * @return InternalFolderOut|false
 	 */
 	protected function getFolder(InputInterface $input, OutputInterface $output) {
 		$folderId = (int)$input->getArgument('folder_id');

lib/Controller/DelegationController.php

@@ -8,9 +8,12 @@
 namespace OCA\GroupFolders\Controller;
 
 use OCA\Circles\CirclesManager;
+use OCA\GroupFolders\Attribute\RequireGroupFolderAdmin;
+use OCA\GroupFolders\ResponseDefinitions;
 use OCA\GroupFolders\Service\DelegationService;
 use OCA\Settings\Service\AuthorizedGroupService;
 use OCP\App\IAppManager;
+use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCSController;
 use OCP\IConfig;
@@ -20,6 +23,10 @@
 use Psr\Container\ContainerExceptionInterface;
 use Psr\Container\ContainerInterface;
 
+/**
+ * @psalm-import-type GroupFoldersDelegationGroup from ResponseDefinitions
+ * @psalm-import-type GroupFoldersDelegationCircle from ResponseDefinitions
+ */
 class DelegationController extends OCSController {
 	public function __construct(
 		string $appName,
@@ -39,6 +46,9 @@ public function __construct(
 	 *
 	 * @NoAdminRequired
 	 * @RequireGroupFolderAdmin
+	 * @return DataResponse<Http::STATUS_OK, list<GroupFoldersDelegationGroup>, array{}>
+	 *
+	 * 200: All groups returned
 	 */
 	public function getAllGroups(): DataResponse {
 		// Get all groups
@@ -61,6 +71,9 @@ public function getAllGroups(): DataResponse {
 	 *
 	 * @NoAdminRequired
 	 * @RequireGroupFolderAdmin
+	 * @return DataResponse<Http::STATUS_OK, list<GroupFoldersDelegationCircle>, array{}>
+	 *
+	 * 200: All circles returned
 	 */
 	public function getAllCircles(): DataResponse {
 		$circlesEnabled = $this->appManager->isEnabledForUser('circles');
@@ -94,12 +107,15 @@ public function getAllCircles(): DataResponse {
 
 	/**
 	 * Get the list Groups related to classname.
-	 * If the classname is
-	 * 	- OCA\GroupFolders\Settings\Admin : It's reference to fields in Admin Priveleges.
-	 * 	- OCA\GroupFolders\Controller\DelegationController : It's just to specific the subadmins.
-	 *	  They can only manage groupfolders in which they are added in the Advanced Permissions (groups only)
+	 * @param string $classname If the classname is
+	 *                          - OCA\GroupFolders\Settings\Admin : It's reference to fields in Admin Privileges.
+	 *                          - OCA\GroupFolders\Controller\DelegationController : It's just to specific the subadmins.
+	 *                          They can only manage groupfolders in which they are added in the Advanced Permissions (groups only)
 	 * @NoAdminRequired
 	 * @RequireGroupFolderAdmin
+	 * @return DataResponse<Http::STATUS_OK, list<GroupFoldersDelegationGroup>, array{}>
+	 *
+	 * 200: Authorized groups returned
 	 */
 	public function getAuthorizedGroups(string $classname = ""): DataResponse {
 		$data = [];