Merge pull request #57 from nextcloud/enh/add-dev-doc

Developer doc

.github/workflows/openapi.yml

@@ -0,0 +1,85 @@
+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@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+
+      - name: Get php version
+        id: versions
+        uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.3.1
+
+      - name: Set up php
+        uses: shivammathur/setup-php@a4e22b60bbb9c1021113f2860347b0759f66fe5d # v2
+        with:
+          php-version: ${{ steps.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@8205673bab74a63eb9b8093402fd9e0e018663a1 # v2.2
+        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@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        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

.gitignore

@@ -7,7 +7,6 @@ js/
 .*.sw*
 node_modules
 .php*.cache
-/composer.lock
 
 /vendor/
 /tests/.phpunit*cache

composer.json

@@ -21,7 +21,7 @@
 		"cs:fix": "php-cs-fixer fix",
 		"psalm": "psalm.phar --no-cache",
 		"test:unit": "phpunit --config tests/phpunit.xml",
-		"openapi": "generate-spec --verbose --allow-missing-docs --continue-on-error"
+		"openapi": "generate-spec --verbose"
 	},
 	"repositories": [
 		{