ci: GH-17 Automating regular spec updates (#21)

* ci: GH-17 Adding update-sdk workflow

* ci: GH-17 Using mkdocs-awesome-nav to automatically include files in their respective nav sections

* ci: GH-17 Adding changeset when running update-sdk

* ci: GH-17 Adding codeowners file and automerge setup for the PR created by update-sdk

* ci: GH-17 Adding workflow_dispatch to update-sdk triggers

* ci: GH-17 Removing check for SDK needing to be up to date on every PR

Author: Tohaker

.devcontainer/devcontainer.json

@@ -8,7 +8,7 @@
 	// Features to add to the dev container. More info: https://containers.dev/features.
 	"features": {
 		"ghcr.io/devcontainers-extra/features/mkdocs:2": {
-			"plugins": "mkdocs-material mkdocs-exclude"
+			"plugins": "mkdocs-material mkdocs-exclude mkdocs-awesome-nav"
 		},
 		"ghcr.io/devcontainers/features/docker-in-docker:2": {
 			"moby": false

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @Tohaker

.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
 
       - uses: actions/setup-python@v6
         with:
-          python-version: '3.13'
+          python-version: "3.13"
 
       - name: Install openapi-spec-validator
         run: pip install openapi-spec-validator
@@ -38,11 +38,5 @@ jobs:
         with:
           go-version-file: go.mod
 
-      - name: Generate SDK
-        run: make all
-
-      - name: Check for uncommitted changes
-        run: |
-          if [[ -n $(git status --porcelain) ]]; then
-              echo "::error::SDK changes detected. Make sure you have pushed all generated changes" && exit 1
-          fi
+      - name: Check SDK builds
+        run: make tidy verify

.github/workflows/deploy-docs.yml

@@ -7,14 +7,15 @@ on:
     paths:
       - mkdocs.yml
       - omada/README.md
-      - 'omada/docs/**'
+      - omada/.nav.yml
+      - "omada/docs/**"
 
 permissions:
   contents: write
 
 jobs:
   deploy:
-    runs-on: ubuntu-slim
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
 
@@ -27,15 +28,15 @@ jobs:
         with:
           python-version: 3.x
 
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
 
       - uses: actions/cache@v5
         with:
           key: mkdocs-material-${{ env.cache_id }}
-          path: ~/.cache 
+          path: ~/.cache
           restore-keys: |
             mkdocs-material-
 
-      - run: pip install mkdocs-material mkdocs-exclude
-       
-      - run: mkdocs gh-deploy --force
+      - run: pip install mkdocs-material mkdocs-exclude mkdocs-awesome-nav
+
+      - run: mkdocs gh-deploy --force

.github/workflows/update-sdk.yml

@@ -0,0 +1,68 @@
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 1 * * *"
+
+permissions:
+  contents: write
+  pull-requests: write
+
+env:
+  BRANCH: chore/update-sdk
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email github-actions[bot]@users.noreply.github.com
+
+      - uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+
+      - name: Generate SDK
+        run: make all
+
+      - name: Check for changes
+        id: check_changes
+        run: |
+          if [[ -n $(git status --porcelain) ]]; then
+              echo "has_changes=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create changeset
+        if: ${{ steps.check_changes.outputs.has_changes == 'true' }}
+        run: |
+          mkdir -p .changeset/
+          cat <<EOF > .changeset/update_sdk_changeset.md
+          ---
+          omada-go-sdk: minor
+          ---
+
+          chore: Updating generated SDK to match latest OpenAPI spec
+          EOF
+
+      - name: Commit and push changes
+        if: ${{ steps.check_changes.outputs.has_changes == 'true' }}
+        run: |
+          git checkout -B "${{ env.BRANCH }}"
+          git add --all
+          git commit -m "chore: update generated SDK"
+          git push --force origin "${{ env.BRANCH }}"
+
+      - name: Create PR
+        if: ${{ steps.check_changes.outputs.has_changes == 'true' }}
+        run: |
+          existing=$(gh pr list --head ${{ env.BRANCH }} --json number --jq '.[0].number')
+          if [[ -z "$existing" ]]; then
+              gh pr create \
+                  --title "chore: update generated SDK" \
+                  --body "Automated SDK regeneration from latest OpenAPI spec." \
+                  --head ${{ env.BRANCH }}
+              gh pr merge --auto --squash
+          fi

.vscode/settings.json

@@ -2,13 +2,14 @@
   "yaml.schemas": {
     "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
   },
-  "yaml.customTags": [ 
+  "yaml.customTags": [
     "!ENV scalar",
     "!ENV sequence",
     "!relative scalar",
     "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
     "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
     "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format",
     "tag:yaml.org,2002:python/object/apply:pymdownx.slugs.slugify mapping"
-  ]
+  ],
+  "makefile.configureOnOpen": false
 }

README.md

@@ -143,6 +143,7 @@ Otherwise, if you haven't done so already, follow their [getting started](https:
 
 You must also install the following extra plugins;
 - `mkdocs-exclude`
+- `mkdocs-awesome-nav`
 
 To preview the docs locally, just run
 

mkdocs.yml

@@ -25,158 +25,9 @@ theme:
         icon: material/brightness-4
         name: Switch to system preference
 docs_dir: omada
-nav:
-  - Home: README.md
-  - SDK Reference:
-    - Abnormal Detect: docs/AbnormalDetectAPI.md
-    - Access Control: docs/AccessControlAPI.md
-    - Access Control Template: docs/AccessControlTemplateAPI.md
-    - ACL: docs/ACLAPI.md
-    - ACL Template: docs/ACLTemplateAPI.md
-    - AP: docs/ApAPI.md
-    - Application Control: docs/ApplicationControlAPI.md
-    - ARP Detection: docs/ArpDetectionAPI.md
-    - Attack Defense: docs/AttackDefenseAPI.md
-    - Attack Defense Template: docs/AttackDefenseTemplateAPI.md
-    - Audit Log: docs/AuditLogAPI.md
-    - Audit Log Template: docs/AuditLogTemplateAPI.md
-    - Authentication: docs/AuthenticationAPI.md
-    - Authentication Template: docs/AuthenticationTemplateAPI.md
-    - Authorize: docs/AuthorizeAPI.md
-    - Authorized Client: docs/AuthorizedClientAPI.md
-    - Backup and Restore: docs/BackupAndRestoreAPI.md
-    - Bandwidth Control: docs/BandwidthControlAPI.md
-    - Bandwidth Control Template: docs/BandwidthControlTemplateAPI.md
-    - Batch OpenAPI: docs/BatchOpenAPIAPI.md
-    - Bluetooth: docs/BluetoothAPI.md
-    - Bluetooth Template: docs/BluetoothTemplateAPI.md
-    - Cert Profiles: docs/CertProfilesAPI.md
-    - Cert Profiles Template: docs/CertProfilesTemplateAPI.md
-    - CLI: docs/CLIAPI.md
-    - CLI Template: docs/CLITemplateAPI.md
-    - Client: docs/ClientAPI.md
-    - Client Insight: docs/ClientInsightAPI.md
-    - Cloud User: docs/CloudUserAPI.md
-    - Cluster: docs/ClusterAPI.md
-    - Controller Settings: docs/ControllerSettingsAPI.md
-    - Customer: docs/CustomerAPI.md
-    - Dashboard: docs/DashboardAPI.md
-    - Data Export: docs/DataExportAPI.md
-    - Device: docs/DeviceAPI.md
-    - Device Management Setting: docs/DeviceManagementSettingAPI.md
-    - DHCP Snooping: docs/DhcpSnoopingAPI.md
-    - Disable NAT: docs/DisableNatAPI.md
-    - EoGRE Tunnel: docs/EoGRETunnelAPI.md
-    - Firewall: docs/FirewallAPI.md
-    - Firewall Template: docs/FirewallTemplateAPI.md
-    - Firmware: docs/FirmwareAPI.md
-    - Form Auth Data: docs/FormAuthDataAPI.md
-    - Gateway: docs/GatewayAPI.md
-    - Gateway QoS: docs/GatewayQoSAPI.md
-    - Gateway QoS Template: docs/GatewayQOSTemplateAPI.md
-    - Gateway Template: docs/GatewayTemplateAPI.md
-    - Global Dashboard Overview: docs/GlobalDashboardOverviewAPI.md
-    - Global Security: docs/GlobalSecurityAPI.md
-    - Health: docs/HealthAPI.md
-    - History Data Retention: docs/HistoryDataRetentionAPI.md
-    - Hotspot Operators: docs/HotspotOperatorsAPI.md
-    - IDSIPS: docs/IDSIPSAPI.md
-    - IDSIPS Template: docs/IDSIPSTemplateAPI.md
-    - Insight: docs/InsightAPI.md
-    - IntelliRecover Client: docs/IntelliRecoverClientAPI.md
-    - IntelliRecover Device: docs/IntelliRecoverDeviceAPI.md
-    - IP-MAC Binding: docs/IPMACBindingAPI.md
-    - IP-MAC Binding Template: docs/IPMACBindingTemplateAPI.md
-    - LAN Multicast: docs/LanMulticastAPI.md
-    - LAN Multicast Template: docs/LanMulticastTemplateAPI.md
-    - License: docs/LicenseAPI.md
-    - Local User: docs/LocalUserAPI.md
-    - Log: docs/LogAPI.md
-    - Log Template: docs/LogTemplateAPI.md
-    - MAC Filtering: docs/MACFilteringAPI.md
-    - MAC Filtering Template: docs/MACFilteringTemplateAPI.md
-    - MLAG: docs/MlagAPI.md
-    - MSP Batch OpenAPI: docs/MSPBatchOpenAPIAPI.md
-    - MSP Device: docs/MSPDeviceAPI.md
-    - MSP History Data Retention: docs/MSPHistoryDataRetentionAPI.md
-    - MSP License: docs/MspLicenseAPI.md
-    - MSP Log: docs/MspLogAPI.md
-    - MSP Setting: docs/MspSettingAPI.md
-    - MSP Site: docs/MSPSiteAPI.md
-    - MSP SSO: docs/MSPSSOAPI.md
-    - MSP User and Role: docs/MSPUserAndRoleAPI.md
-    - MSP Webhook Setting: docs/MspWebhookSettingAPI.md
-    - NAT: docs/NATAPI.md
-    - NAT Template: docs/NATTemplateAPI.md
-    - Network Analyze: docs/NetworkAnalyzeAPI.md
-    - Network Report: docs/NetworkReportAPI.md
-    - OLT: docs/OLTAPI.md
-    - OLT DBA: docs/OLTDBAAPI.md
-    - OLT GEM Mapping: docs/OLTGemMappingAPI.md
-    - OLT GEM Port: docs/OLTGemPortAPI.md
-    - OLT Line Profile: docs/OLTLineProfileAPI.md
-    - OLT ONT Port: docs/OLTONTPortAPI.md
-    - OLT ONU Management: docs/OLTONUManagementAPI.md
-    - OLT ONU Register: docs/OLTONURegisterAPI.md
-    - OLT PON Port: docs/OLTPonPortAPI.md
-    - OLT Service Port: docs/OLTServicePortAPI.md
-    - OLT Service Port Profile: docs/OLTServicePortProfileAPI.md
-    - OLT Service Profile: docs/OLTServiceProfileAPI.md
-    - OLT TCont: docs/OLTTContAPI.md
-    - OLT Traffic Profile: docs/OLTTrafficProfileAPI.md
-    - OSPF: docs/OSPFAPI.md
-    - OUI-Based VLAN: docs/OUIBasedVLANAPI.md
-    - OUI-Based VLAN Template: docs/OUIBasedVLANTemplateAPI.md
-    - Profiles: docs/ProfilesAPI.md
-    - Profiles Template: docs/ProfilesTemplateAPI.md
-    - Quick Action: docs/QuickActionAPI.md
-    - Remote Access: docs/RemoteAccessAPI.md
-    - Report V2: docs/ReportV2API.md
-    - Routing: docs/RoutingAPI.md
-    - Routing Template: docs/RoutingTemplateAPI.md
-    - RRM: docs/RrmAPI.md
-    - Schedule: docs/ScheduleAPI.md
-    - Schedule Template: docs/ScheduleTemplateAPI.md
-    - SD-WAN: docs/SDWANAPI.md
-    - Service: docs/ServiceAPI.md
-    - Service Template: docs/ServiceTemplateAPI.md
-    - Session Limit: docs/SessionLimitAPI.md
-    - Session Limit Template: docs/SessionLimitTemplateAPI.md
-    - SIM: docs/SIMAPI.md
-    - SIM Template: docs/SIMTemplateAPI.md
-    - Site: docs/SiteAPI.md
-    - Site Configuration: docs/SiteConfigurationAPI.md
-    - Site Template: docs/SiteTemplateAPI.md
-    - Site Template Configuration: docs/SiteTemplateConfigurationAPI.md
-    - SSL VPN: docs/SSLVPNAPI.md
-    - SSO: docs/SSOAPI.md
-    - Stack: docs/StackAPI.md
-    - Statistic: docs/StatisticAPI.md
-    - Switch: docs/SwitchAPI.md
-    - Switch QoS: docs/SwitchQoSAPI.md
-    - Switch Template: docs/SwitchTemplateAPI.md
-    - System Settings: docs/SystemSettingsAPI.md
-    - Threat Management: docs/ThreatManagementAPI.md
-    - Topology: docs/TopologyAPI.md
-    - URL Filtering: docs/URLFilteringAPI.md
-    - URL Filtering Template: docs/URLFilteringTemplateAPI.md
-    - User and Role: docs/UserAndRoleAPI.md
-    - VoIP: docs/VoIPAPI.md
-    - VoIP Template: docs/VoIPTemplateAPI.md
-    - Voucher: docs/VoucherAPI.md
-    - VPN: docs/VPNAPI.md
-    - VRRP: docs/VRRPAPI.md
-    - Webhook Setting: docs/WebhookSettingAPI.md
-    - Wired Network: docs/WiredNetworkAPI.md
-    - Wired Network Template: docs/WiredNetworkTemplateAPI.md
-    - WireGuard VPN: docs/WireguardVPNAPI.md
-    - Wireless IDSIPS: docs/WirelessIDSIPSAPI.md
-    - Wireless IDSIPS Template: docs/WirelessIDSIPSTemplateAPI.md
-    - Wireless Network: docs/WirelessNetworkAPI.md
-    - Wireless Network Template: docs/WirelessNetworkTemplateAPI.md
-    - WLAN Optimization: docs/WLANOptimizationAPI.md
 plugins:
   - search
+  - awesome-nav
   - exclude:
       glob:
         - /.openapi-generator

omada/.nav.yml

@@ -0,0 +1,7 @@
+nav:
+  - Home: README.md
+  - API Reference:
+    - "docs/*API.md"
+  - Model Reference:
+    - glob: "docs/*.md"
+      ignore: "docs/*API.md"

omada/.openapi-generator-ignore

@@ -11,3 +11,5 @@ git_push.sh
 # Travis CI config (not needed)
 .travis.yml
 
+# mkdocs-awesome-nav
+.nav.yml