docs: add documentation #1
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Generate Swagger UI for API specs of data models | |
| on: | |
| push: | |
| # Adjust branches as needed | |
| branches: | |
| - '**' | |
| jobs: | |
| set-matrix: | |
| runs-on: ubuntu-latest | |
| concurrency: | |
| group: gh-pages-deployment | |
| cancel-in-progress: false | |
| outputs: | |
| matrix: ${{ steps.build-matrix.outputs.matrix }} | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v2 | |
| - name: Find API spec files and build matrix | |
| id: build-matrix | |
| run: | | |
| # Find all YAML files under any "api_docs" directory | |
| specs=$(find . -type f -path "*/api_docs/*.yaml") | |
| echo "Found spec files:" | |
| echo "$specs" | |
| # Build a JSON matrix: for each spec, the output directory is under the same api_docs folder. | |
| matrix="[]" | |
| for spec in $specs; do | |
| # Remove the .yaml extension from the file name | |
| base=$(basename "$spec" .yaml) | |
| # Get the directory of the spec file | |
| spec_dir=$(dirname "$spec") | |
| # For each spec, the generated output will reside in: <spec_dir>/swagger-ui/<basename> | |
| output_dir="${spec_dir}/swagger-ui/${base}" | |
| newEntry="{\"spec\":\"${spec}\", \"output\":\"${output_dir}\"}" | |
| if [ "$matrix" = "[]" ]; then | |
| matrix="[$newEntry]" | |
| else | |
| matrix="${matrix%]}" | |
| matrix+=",${newEntry}]" | |
| fi | |
| done | |
| echo "Matrix JSON: $matrix" | |
| # Set the matrix output (using the new recommended GITHUB_OUTPUT mechanism) | |
| echo "matrix=$matrix" >> $GITHUB_OUTPUT | |
| update-docs: | |
| needs: set-matrix | |
| runs-on: ubuntu-latest | |
| strategy: | |
| # Use the dynamically generated matrix. | |
| # Each job will process one API spec file. | |
| matrix: | |
| include: ${{ fromJson(needs.set-matrix.outputs.matrix) }} | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| - name: Create output folder if not present | |
| run: mkdir -p "${{ matrix.output }}" | |
| - name: Generate Swagger UI for ${{ matrix.spec }} | |
| uses: Legion2/swagger-ui-action@v1 | |
| with: | |
| # The file to process from the matrix. | |
| spec-file: ${{ matrix.spec }} | |
| # The output directory, computed in the matrix (e.g. swagger-ui/ActuatorFiware) | |
| output: ${{ matrix.output }} | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| - name: Deploy to GitHub Pages | |
| uses: peaceiris/actions-gh-pages@v4 | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| # Change the publish_dir to the folder you want served. | |
| # For example, here we deploy everything under "example_building_automation/api_docs" | |
| # which includes the generated swagger-ui subfolders. | |
| publish_dir: ${{ matrix.output }} | |
| destination_dir: ${{ matrix.output }} | |
| # - name: Commit generated Swagger UI files | |
| # run: | | |
| # git config --global user.name "github-actions[bot]" | |
| # git config --global user.email "github-actions[bot]@users.noreply.github.com" | |
| # # Stage only changes in the api_docs folders | |
| # git add **/api_docs/swagger-ui | |
| # # Commit if there are changes | |
| # git commit -m "Update generated Swagger UI for ${{ matrix.spec }}" || echo "No changes to commit" | |
| # git push | |
| # deploy-pages: | |
| # needs: update-docs | |
| # runs-on: ubuntu-latest | |
| # steps: | |
| # - name: Checkout repository | |
| # uses: actions/checkout@v2 | |
| # with: | |
| # # Ensure the latest commits are checked out | |
| # fetch-depth: 0 | |
| # | |
| # - name: Deploy to GitHub Pages | |
| # uses: peaceiris/actions-gh-pages@v3 | |
| # with: | |
| # github_token: ${{ secrets.GITHUB_TOKEN }} | |
| # # Change the publish_dir to the folder you want served. | |
| # # For example, here we deploy everything under "example_building_automation/api_docs" | |
| # # which includes the generated swagger-ui subfolders. | |
| # publish_dir: example_building_automation/api_docs |