(fix) Umbau zu SCS

### 1.1 OpenAPI-Dokumentation implementieren - Swagger/OpenAPI in bestehenden Ktor-Diensten integrieren - Zentrale API-Dokumentationsseite im API-Gateway erstellen - CI/CD-Pipeline um automatische API-Dokumentationsgenerierung erweitern - Entwickler-Guidelines für API-Dokumentation erstellen
2025-07-21 13:45:58 +02:00
parent 77953c18f6
commit 81e40e70fc
13 changed files with 3192 additions and 72 deletions
@@ -0,0 +1,124 @@
+name: API Documentation Generator
+
+on:
+  push:
+    branches: [ main, master ]
+    paths:
+      - 'api-gateway/src/jvmMain/resources/openapi/**'
+      - 'api-gateway/src/jvmMain/kotlin/at/mocode/gateway/routing/**'
+      - 'api-gateway/src/jvmMain/kotlin/at/mocode/gateway/config/OpenApiConfig.kt'
+      - 'api-gateway/build.gradle.kts'
+      - '.github/workflows/api-docs.yml'
+  pull_request:
+    branches: [ main, master ]
+    paths:
+      - 'api-gateway/src/jvmMain/resources/openapi/**'
+      - 'api-gateway/src/jvmMain/kotlin/at/mocode/gateway/routing/**'
+      - 'api-gateway/src/jvmMain/kotlin/at/mocode/gateway/config/OpenApiConfig.kt'
+      - 'api-gateway/build.gradle.kts'
+      - '.github/workflows/api-docs.yml'
+  workflow_dispatch:  # Allow manual triggering
+  schedule:
+    - cron: '0 0 * * 0'  # Run weekly on Sunday at midnight
+
+jobs:
+  validate-openapi:
+    name: Validate OpenAPI Specification
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Validate OpenAPI
+        uses: char0n/swagger-editor-validate@v1
+        with:
+          definition-file: api-gateway/src/jvmMain/resources/openapi/documentation.yaml
+
+  generate-api-docs:
+    name: Generate API Documentation
+    runs-on: ubuntu-latest
+    needs: validate-openapi
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'temurin'
+          cache: gradle
+
+      - name: Grant execute permission for gradlew
+        run: chmod +x gradlew
+
+      - name: Generate API Documentation
+        id: generate-docs
+        run: ./gradlew :api-gateway:generateApiDocs
+
+      - name: Check for changes
+        id: git-check
+        run: |
+          if git diff --exit-code api-gateway/src/jvmMain/resources/static/docs/; then
+            echo "changed=false" >> $GITHUB_OUTPUT
+          else
+            echo "changed=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Commit and push if changed
+        if: steps.git-check.outputs.changed == 'true'
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+          git add api-gateway/src/jvmMain/resources/static/docs/
+          git commit -m "Update API documentation [skip ci]"
+          git push
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Upload documentation artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: api-documentation
+          path: api-gateway/src/jvmMain/resources/static/docs/
+          retention-days: 7
+
+      - name: Notify on success
+        if: steps.git-check.outputs.changed == 'true'
+        run: |
+          echo "API documentation has been updated successfully."
+          # Uncomment and configure when notification service is available
+          # curl -X POST -H 'Content-type: application/json' --data '{"text":"API documentation has been updated successfully."}' ${{ secrets.SLACK_WEBHOOK_URL }}
+
+  deploy-to-github-pages:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    needs: generate-api-docs
+    # Only deploy on main/master branch, not on PRs
+    if: github.event_name != 'pull_request' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master')
+
+    steps:
+      - name: Download documentation artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: api-documentation
+          path: ./docs
+
+      - name: Setup GitHub Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload GitHub Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+      - name: Output deployment URL
+        run: |
+          echo "Documentation deployed to ${{ steps.deployment.outputs.page_url }}"
+          # Uncomment and configure when notification service is available
+          # curl -X POST -H 'Content-type: application/json' --data '{"text":"API documentation deployed to ${{ steps.deployment.outputs.page_url }}"}' ${{ secrets.SLACK_WEBHOOK_URL }}