Add OpenAPI support

.github/workflows/openapi.yml

@@ -0,0 +1,96 @@
+# 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 <[email protected]>
+# 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@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+
+      - name: Get php version
+        id: php_versions
+        uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.3.1
+
+      - name: Set up php
+        uses: shivammathur/setup-php@cf4cade2721270509d5b1c766ab3549210a39a2a # v2.33.0
+        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@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        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
+        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

.php-cs-fixer.dist.php

@@ -5,7 +5,7 @@
  * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
-require_once './vendor/autoload.php';
+require_once './vendor-bin/cs-fixer/vendor/autoload.php';
 
 use Nextcloud\CodingStandard\Config;
 

REUSE.toml

@@ -58,3 +58,9 @@ path = ["js/**.mjs.map"]
 precedence = "aggregate"
 SPDX-FileCopyrightText = "2019 Nextcloud GmbH and Nextcloud contributors"
 SPDX-License-Identifier = "AGPL-3.0-or-later"
+
+[[annotations]]
+path = ["openapi.json", "vendor-bin/cs-fixer/*", "vendor-bin/openapi-extractor/*", "vendor-bin/phpunit/*", "vendor-bin/psalm/*"]
+precedence = "aggregate"
+SPDX-FileCopyrightText = "2025 Nextcloud GmbH and Nextcloud contributors"
+SPDX-License-Identifier = "AGPL-3.0-or-later"

appinfo/routes.php

@@ -10,22 +10,22 @@
 return [
 	'ocs' => [
 		# v1
-		['name' => 'Key#setPrivateKey', 'url' => '/api/v{apiVersion}/private-key', 'verb' => 'POST', 'requirements' => ['apiVersion' => '[1-2]']],
-		['name' => 'Key#getPrivateKey', 'url' => '/api/v{apiVersion}/private-key', 'verb' => 'GET', 'requirements' => ['apiVersion' => '[1-2]']],
-		['name' => 'Key#deletePrivateKey', 'url' => '/api/v{apiVersion}/private-key', 'verb' => 'DELETE', 'requirements' => ['apiVersion' => '[1-2]']],
-		['name' => 'Key#setPublicKey', 'url' => '/api/v{apiVersion}/public-key', 'verb' => 'PUT', 'requirements' => ['apiVersion' => '[1-2]']],
-		['name' => 'Key#createPublicKey', 'url' => '/api/v{apiVersion}/public-key', 'verb' => 'POST', 'requirements' => ['apiVersion' => '[1-2]']],
-		['name' => 'Key#getPublicKeys', 'url' => '/api/v{apiVersion}/public-key', 'verb' => 'GET', 'requirements' => ['apiVersion' => '[1-2]']],
-		['name' => 'Key#deletePublicKey', 'url' => '/api/v{apiVersion}/public-key', 'verb' => 'DELETE', 'requirements' => ['apiVersion' => '[1-2]']],
-		['name' => 'Key#getPublicServerKey', 'url' => '/api/v{apiVersion}/server-key', 'verb' => 'GET', 'requirements' => ['apiVersion' => '[1-2]']],
+		['name' => 'Key#setPrivateKey', 'url' => '/api/v{apiVersion}/private-key', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(1|2)']],
+		['name' => 'Key#getPrivateKey', 'url' => '/api/v{apiVersion}/private-key', 'verb' => 'GET', 'requirements' => ['apiVersion' => '(1|2)']],
+		['name' => 'Key#deletePrivateKey', 'url' => '/api/v{apiVersion}/private-key', 'verb' => 'DELETE', 'requirements' => ['apiVersion' => '(1|2)']],
+		['name' => 'Key#setPublicKey', 'url' => '/api/v{apiVersion}/public-key', 'verb' => 'PUT', 'requirements' => ['apiVersion' => '(1|2)']],
+		['name' => 'Key#createPublicKey', 'url' => '/api/v{apiVersion}/public-key', 'verb' => 'POST', 'requirements' => ['apiVersion' => '(1|2)']],
+		['name' => 'Key#getPublicKeys', 'url' => '/api/v{apiVersion}/public-key', 'verb' => 'GET', 'requirements' => ['apiVersion' => '(1|2)']],
+		['name' => 'Key#deletePublicKey', 'url' => '/api/v{apiVersion}/public-key', 'verb' => 'DELETE', 'requirements' => ['apiVersion' => '(1|2)']],
+		['name' => 'Key#getPublicServerKey', 'url' => '/api/v{apiVersion}/server-key', 'verb' => 'GET', 'requirements' => ['apiVersion' => '(1|2)']],
 		['name' => 'V1\MetaData#setMetaData', 'url' => '/api/v1/meta-data/{id}', 'verb' => 'POST'],
 		['name' => 'V1\MetaData#getMetaData', 'url' => '/api/v1/meta-data/{id}', 'verb' => 'GET'],
 		['name' => 'V1\MetaData#updateMetaData', 'url' => '/api/v1/meta-data/{id}', 'verb' => 'PUT'],
 		['name' => 'V1\MetaData#deleteMetaData', 'url' => '/api/v1/meta-data/{id}', 'verb' => 'DELETE'],
 		['name' => 'V1\MetaData#addMetadataFileDrop', 'url' => '/api/v1/meta-data/{id}/filedrop', 'verb' => 'PUT'],
-		['name' => 'Encryption#removeEncryptedFolders', 'url' => '/api/v{apiVersion}/encrypted-files', 'verb' => 'DELETE', 'requirements' => ['apiVersion' => '[1-2]']],
-		['name' => 'Encryption#setEncryptionFlag', 'url' => '/api/v{apiVersion}/encrypted/{id}', 'verb' => 'PUT', 'requirements' => ['apiVersion' => '[1-2]']],
-		['name' => 'Encryption#removeEncryptionFlag', 'url' => '/api/v{apiVersion}/encrypted/{id}', 'verb' => 'DELETE', 'requirements' => ['apiVersion' => '[1-2]']],
+		['name' => 'Encryption#removeEncryptedFolders', 'url' => '/api/v{apiVersion}/encrypted-files', 'verb' => 'DELETE', 'requirements' => ['apiVersion' => '(1|2)']],
+		['name' => 'Encryption#setEncryptionFlag', 'url' => '/api/v{apiVersion}/encrypted/{id}', 'verb' => 'PUT', 'requirements' => ['apiVersion' => '(1|2)']],
+		['name' => 'Encryption#removeEncryptionFlag', 'url' => '/api/v{apiVersion}/encrypted/{id}', 'verb' => 'DELETE', 'requirements' => ['apiVersion' => '(1|2)']],
 		['name' => 'V1\Locking#lockFolder', 'url' => '/api/v1/lock/{id}', 'verb' => 'POST'],
 		['name' => 'V1\Locking#unlockFolder', 'url' => '/api/v1/lock/{id}', 'verb' => 'DELETE'],
 		# v2

composer.json

@@ -9,24 +9,30 @@
 		}
 	],
 	"require-dev": {
-		"phpunit/phpunit": "^9.5",
-		"psalm/phar": "^5.25",
-		"nextcloud/coding-standard": "^1.0",
-		"nextcloud/ocp": "dev-master"
+		"nextcloud/ocp": "dev-master",
+		"bamarni/composer-bin-plugin": "^1.8"
 	},
 	"scripts": {
+		"post-install-cmd": [
+			"@composer bin all install --ansi"
+		],
+		"post-update-cmd": [
+			"@composer bin all update --ansi"
+		],
 		"lint": "find . -name \\*.php -not -path './vendor/*' -print0 | xargs -0 -n1 php -l",
 		"cs:check": "php-cs-fixer fix --dry-run --diff",
 		"cs:fix": "php-cs-fixer fix",
-		"psalm": "psalm.phar --threads=1",
-		"psalm:update-baseline": "psalm.phar --threads=1 --update-baseline",
-		"psalm:clear": "psalm.phar --clear-cache && psalm --clear-global-cache",
-		"psalm:fix": "psalm.phar --alter --issues=InvalidReturnType,InvalidNullableReturnType,MissingParamType,InvalidFalsableReturnType",
-		"test:unit": "phpunit --configuration tests/phpunit.xml"
+		"psalm": "psalm --threads=1",
+		"psalm:update-baseline": "psalm --threads=1 --update-baseline",
+		"psalm:clear": "psalm --clear-cache && psalm --clear-global-cache",
+		"psalm:fix": "psalm --alter --issues=InvalidReturnType,InvalidNullableReturnType,MissingParamType,InvalidFalsableReturnType",
+		"test:unit": "phpunit --configuration tests/phpunit.xml",
+		"openapi": "generate-spec"
 	},
 	"config": {
 		"allow-plugins": {
-			"composer/package-versions-deprecated": true
+			"composer/package-versions-deprecated": true,
+			"bamarni/composer-bin-plugin": true
 		},
 		"platform": {
 			"php": "8.3"