81e40e70fc
### 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
125 lines
4.2 KiB
YAML
125 lines
4.2 KiB
YAML
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 }}
|