sync

.github/copilot-instructions.md

@@ -0,0 +1,46 @@
+# GitHub Copilot Instructions for mist_openapi Project
+
+## Project Structure
+- **Source of Truth**: `workdir/openapi.yaml` is the primary file
+- **Generated Files**: Root-level files are auto-generated from `workdir/openapi.yaml`:
+  - `mist.openapi.json`
+  - `mist.openapi.yaml`
+  - `mist.postman.json`
+  - `mist.postman.v2.json`
+  - `mist.postman_env.json`
+- **Generation Script**: `workdir/generate.sh` (and related Python scripts) creates all generated files
+
+## PR Review Guidelines
+
+### OpenAPI File Changes (`workdir/openapi.yaml`)
+When reviewing changes to `workdir/openapi.yaml`:
+1. ✅ Verify `info.version` field has been updated with new version
+2. ✅ Verify `info.description` field has been updated with new release date and version information (release date up to one day in the future is acceptable)
+3. ✅ Check that generated files are present and correctly updated
+4. ✅ Confirm `CHANGELOG.md` has an entry for the new OpenAPI version
+5. ✅ Validate OpenAPI schema syntax and structure
+6. ✅ Ensure backward compatibility or document breaking changes
+
+### Commit Review Strategy
+- Focus comments on `workdir/openapi.yaml` changes
+- Do NOT repeat the same comment across generated files
+- Only flag generated files if they're missing or incorrectly generated
+
+### Schema Quality Checks
+- ✅ Validate the OAS format against OpenAPI Specification version 3.1
+- ✅ Endpoint paths follow RESTful conventions
+- ✅ Request/response schemas are well-defined
+- ✅ Required fields are clearly marked
+- ✅ Examples are provided for complex schemas
+- ✅ Descriptions are clear and accurate
+- 🔐 No sensitive data in examples or defaults (it's possible to see fake API Token, MAC Addresses, username, ... in the descriptions and examples)
+
+### Version Management
+- 🔁 Breaking changes must be documented in CHANGELOG.md
+- 🔁 Deprecated endpoints/fields should be marked before removal
+- 📦 Version numbers follow semantic versioning
+
+### Code Quality
+- 🧪 Changes should be validated against OpenAPI specification
+- 📉 Avoid duplicate schema definitions
+- 🛠 Ensure changes work in both staging and production environments

CHANGELOG.md

@@ -2,6 +2,184 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2602.1.9] - 2026-03-19
+
+- Updated schema definitions for `gateway` and `gateway_template`:
+  - Added `gateway_mgmt` field with sub-properties: `admin_sshkeys`, `app_probing`, `app_usage`, `auto_signature_update`, `config_revert_timer`, `disable_console`, `disable_oob`, `disable_usb`, `fips_enabled`, `probe_hosts`, `probe_hostsv6`, `protect_re`, `root_password`, `security_log_source_address`, `security_log_source_interface`
+- Updated schema definitions for `site_setting`:
+  - Consolidated `gateway_mgmt` to use shared `#/components/schemas/gateway_mgmt` schema
+- Removed deprecated schemas (now consolidated into `gateway_mgmt`):
+  - `site_setting_gateway_mgmt`, `site_setting_gateway_mgmt_admin_sshkeys`, `site_setting_gateway_mgmt_auto_signature_update`, `site_setting_gateway_mgmt_probe_hosts`, `site_setting_gateway_mgmt_probe_hostsv6`
+- Added `format: password` to sensitive credential fields across multiple schemas for improved security handling (passwords, secrets, API keys, auth tokens)
+
+## [2602.1.8] - 2026-03-18
+
+- Updated `/api/v1/sites/{site_id}/insights/device/{device_mac}/{metric}`
+  - Added optional `port_id` query parameter for interface-specific metrics
+- Updated `/api/v1/sites/{site_id}/insights/gateway/{device_id}/stats`
+  - Added optional `port_id` query parameter for interface-specific metrics
+- Updated `/api/v1/sites/{site_id}/insights/mxedge/{device_mac}/{metric}`
+  - Added optional `port_id` query parameter for interface-specific metrics
+- Updated `/api/v1/sites/{site_id}/insights/switch/{device_mac}/{metric}`
+  - Added optional `port_id` query parameter for interface-specific metrics
+
+## [2602.1.7] - 2026-03-18
+
+- Added `/api/v1/sites/{site_id}/insights/ap/{device_id}/stats`
+  - New endpoint for AP Insight Metrics with required `metrics` query parameter
+- Updated `/api/v1/orgs/{org_id}/stats`
+  - Removed `start`, `end`, `duration`, `limit`, `page` query parameters not applicable to org-level stats endpoint
+- Updated `/api/v1/orgs/{org_id}/stats/sites`
+  - Removed `start`, `end`, `duration` query parameters not applicable to site-level stats endpoint
+- Updated `/api/v1/sites/{site_id}/insights`
+  - Changed path from `/api/v1/sites/{site_id}/insights/{metric}` to use `metrics` query parameter instead of path parameter
+- Updated `/api/v1/sites/{site_id}/insights/client/{client_mac}`
+  - Changed path from `/api/v1/sites/{site_id}/insights/client/{client_mac}/{metric}` to use `metrics` query parameter instead of path parameter
+- Updated `/api/v1/sites/{site_id}/insights/gateway/{device_id}/stats`
+  - Changed path from `/api/v1/sites/{site_id}/insights/gateway/{device_id}/stats/{metric}` to use `metrics` query parameter instead of path parameter
+- Updated schema definitions for `gateway` and `gateway_template`:
+  - `.oob_ip_configs.vlan_id`, `.oob_ip_configs.node1.vlan_id`: Changed type from `string` to `oneOf` with `string` and `integer` to support both string and numeric VLAN IDs
+
+## [2602.1.6] - 2026-03-05
+
+- Improve query parameter descriptions when partial search is supported with wildcard (`*`) for better clarity on search behavior
+- Updated schema definitions
+  - Added `uplink` field (boolean) to `stats_switch_port` to indicate if interface is an uplink port
+
+## [2602.1.5] - 2026-03-03
+
+- Updated `/api/v1/sites/{site_id}/insights/fingerprints/count` and `/api/v1/sites/{site_id}/insights/fingerprints/search`
+  - Updated operationIds from `countOrgClientFingerprints`/`searchOrgClientFingerprints` to `countSiteClientFingerprints`/`searchSiteClientFingerprints`
+  - Updated tag from `Orgs NAC Fingerprints` to `Sites NAC Fingerprints`
+- Updated `/api/v1/orgs/{org_id}/inventory`
+  - Removed `vc_mac` and `master_mac` query parameters 
+  - Added `model` and `name` query parameters
+  - Updated `status` parameter to use enum reference (`connected`, `disconnected`)
+- Updated `/api/v1/sites/{site_id}/devices/{device_id}/clear_dot1x_mac_limit`
+  - Changed `port_id` to `ports` (array) to support clearing multiple ports
+- Updated `/api/v1/sites/{site_id}/devices/{device_id}/clear_policy_hit_count`
+  - Added `policy_name` request body parameter (required)
+- Updated `/api/v1/sites/{site_id}/devices/{device_id}/show_arp`
+  - Changed tag from `Utilities Common` to `Utilities LAN`
+- Updated schema definitions
+  - `clear_dot1x_session`: changed `port_id` to `ports` (array)
+  - `utils_clear_bpdu`: changed `port` to `ports` (array)
+  - `utils_release_dhcp_leases`: changed `mac` to `macs`
+  - `utils_show_arp`: added `node` field for HA cluster support on Gateways
+
+## [2602.1.4] - 2026-02-26
+
+- Updated `/api/v1/orgs/{org_id}/inventory`
+  - Updated `type` parameter to support multiple comma-separated values from: `ap`, `gateway`, `router`, `switch`, `all` (default: `ap`)
+- Updated `/api/v1/orgs/{org_id}/jsi/inventory/search`
+  - Replaced `eol_duration` and `eos_duration` with date-based filters: `eol_after`, `eol_before`, `eos_after`, `eos_before`
+  - Added `version_eos_after` and `version_eos_before` parameters for software version end-of-support filtering
+  - Added `sirt_id` and `pbn_id` parameters for security advisory filtering
+  - Updated `text` parameter description to clarify wildcard support
+- Updated `/api/v1/sites/{site_id}/devices`
+  - Updated `type` parameter to support multiple comma-separated values from: `ap`, `gateway`, `router`, `switch`, `all` (default: `ap`)
+- Added `/api/v1/sites/{site_id}/mapstacks`
+- Updated `/api/v1/sites/{site_id}/setting`
+  - Added `gateway_tunnel_updown_threshold` field (integer) to enable threshold-based gateway tunnel (secure edge tunnels) up-down delivery
+  - Added `allow_mist` field (boolean) to control whether Mist can access this site
+  - Added `ap_synthetic_test.additional_vlan_ids` field (array of integers) for additional VLAN IDs in synthetic tests
+- Updated webhook schemas
+  - Added new webhook topic `minis-reachability` for AP synthetic test reachability events
+  - Updated `webhook_minis_reachability_event` timestamp field to use shared `#/components/schemas/timestamp` reference for consistency
+  - Added webhook sample endpoint for `minis-reachability` topic at `/webhooks/minis_reachability`
+- Updated schema definitions
+  - Added `wlan.disable_message_authenticator_check` field (boolean) to disable Message-Authenticator Check for RADIUS message integrity verification (default: false for better security)
+  - Updated `extra_route` and `extra_route6` schemas to reference shared `next_hop_via` schema for better reusability and support for ECMP (Equal-Cost Multi-Path) load balancing
+  - Replaced `mapstack_id` and `mapstack_floor` with `group_name` and `group_idx` in map schema for maps grouping (group_idx typically used for floor)
+
+## [2602.1.3] - 2026-02-24
+
+- Updated websocket API examples for clarity and completeness
+- Improved `alarm_group` description
+- Added missing `site_id` query parameter to `searchOrgWanClients`
+- Added missing query parameter `message` and `sort` to `listSelfAuditLogs`
+
+## [2602.1.2] - 2026-02-24
+
+- Updated `/api/v1/sites/{site_id}`
+  - Added `routertemplate_id` field
+- Updated `/api/v1/orgs/{org_id}/sites`
+  - Added `routertemplate_id` field
+
+## [2602.1.1] - 2026-02-19
+
+- Updated `/api/v1/orgs/{org_id}/sites/search`
+  - Updated `name` parameter description to clarify it is case insensitive and supports partial search with wildcard (`*`)
+- Updated `/api/v1/orgs/{org_id}/stats/ports/search`
+  - Removed unsupported `site_id` query parameter
+- Updated schema definitions
+  - Added `deprecated: true` attribute to `managed` and `disable_auto_config` fields
+  - Fixed inline complex definitions
+
+## [2602.1.0] - 2026-02-10
+
+- Added `/api/v1/orgs/{org_id}/aos/register_cmd`
+- Added `/api/v1/orgs/{org_id}/jsi/pbn/count`
+- Added `/api/v1/orgs/{org_id}/jsi/pbn/search`
+- Added `/api/v1/orgs/{org_id}/jsi/sirt/count`
+- Added `/api/v1/orgs/{org_id}/jsi/sirt/search`
+- Added `/api/v1/orgs/{org_id}/mxedges/{mxedge_id}/vm_params`
+- Added `/api/v1/orgs/{org_id}/usermacs/count`
+- Added `/api/v1/sites/{site_id}/maps/auto_geofences`
+  - Run auto geofence service for all maps in a site
+- Added `/api/v1/sites/{site_id}/maps/{map_id}/auto_geofences`
+  - Run auto geofence service for a single map
+- Updated `/api/v1/orgs/{org_id}/nac_clients/search`
+- Updated `/api/v1/orgs/{org_id}/setting`
+  - Added `allow_mist` field
+- Updated `/api/v1/orgs/{org_id}/stats`
+  - Added `allow_mist` field to response
+- Updated `/api/v1/sites/{site_id}/analyze_spectrum`
+  - Added `channels` parameter to request body
+  - Added `minimum: 60` constraint to `duration` parameter
+- Updated `/api/v1/sites/{site_id}/setting/derived`
+  - Added `allow_mist` field to response
+- Updated `/api/v1/sites/{site_id}/stats/devices`
+  - Added `ip`, `mac`, `product_id`, `vendor_id` fields to `esl_stat` for Hanshow and SoluM dongles
+
+## [2511.1.6] - 2025-12-11
+
+- Updated `/api/v1/orgs/{org_id}/networktemplates`
+  Updated `/api/v1/orgs/{org_id}/networktemplates/{networktemplate_id}`
+  Updated `/api/v1/sites/{site_id}/devices`
+  Updated `/api/v1/sites/{site_id}/devices/import`
+  Updated `/api/v1/sites/{site_id}/devices/{device_id}`
+  Updated `/api/v1/sites/{site_id}/networktemplates/derived`
+  Updated `/api/v1/sites/{site_id}/setting`
+  Updated `/api/v1/sites/{site_id}/setting/derived`
+  - Added `bgp_config` for switches
+- Updated `/api/v1/orgs/{org_id}/deviceprofiles`
+  Updated `/api/v1/orgs/{org_id}/deviceprofiles/{deviceprofile_id}`
+  Updated `/api/v1/orgs/{org_id}/evpn_topologies`
+  Updated `/api/v1/orgs/{org_id}/evpn_topologies/{evpn_topology_id}`
+  Updated `/api/v1/orgs/{org_id}/networktemplates`
+  Updated `/api/v1/orgs/{org_id}/networktemplates/{networktemplate_id}`
+  Updated `/api/v1/sites/{site_id}/deviceprofiles/derived`
+  Updated `/api/v1/sites/{site_id}/devices`
+  Updated `/api/v1/sites/{site_id}/devices/import`
+  Updated `/api/v1/sites/{site_id}/devices/{device_id}`
+  Updated `/api/v1/sites/{site_id}/evpn_topologies`
+  Updated `/api/v1/sites/{site_id}/evpn_topologies/{evpn_topology_id}`
+  Updated `/api/v1/sites/{site_id}/networktemplates/derived`
+  Updated `/api/v1/sites/{site_id}/setting`
+  Updated `/api/v1/sites/{site_id}/setting/derived`
+  - Added `networks` to `port_config`
+- Updated `/api/v1/orgs/{org_id}/deviceprofiles`
+  Updated `/api/v1/orgs/{org_id}/deviceprofiles/{deviceprofile_id}`
+  Updated `/api/v1/orgs/{org_id}/gatewaytemplates`
+  Updated `/api/v1/orgs/{org_id}/gatewaytemplates/{gatewaytemplate_id}`
+  Updated `/api/v1/sites/{site_id}/deviceprofiles/derived`
+  Updated `/api/v1/sites/{site_id}/gatewaytemplates/derived`
+  Updated `/api/v1/sites/{site_id}/setting`
+  Updated `/api/v1/sites/{site_id}/setting/derived`
+  - Updated `gateway_matching` to use `gateway_port_config` component for `port_config` property
+
+
 ## [2511.1.0] - 2025-11-17
 
 - Marked `/api/v1/orgs/{org_id}/128routers/register_cmd` as deprecated, replaced by `/api/v1/orgs/{org_id}/ssr/register_cmd`