Closes #20203: Add a pre-commit check for OpenAPI schema changes (#20230)

.pre-commit-config.yaml

@@ -21,6 +21,14 @@ repos:
       language: system
       pass_filenames: false
       types: [python]
+    - id: openapi-check
+      name: "Validate OpenAPI schema"
+      description: "Check for any unexpected changes to the OpenAPI schema"
+      files: api/.*\.py$
+      entry: scripts/verify-openapi.sh
+      language: system
+      pass_filenames: false
+      types: [python]
     - id: mkdocs-build
       name: "Build documentation"
       description: "Build the documentation with mkdocs"

docs/development/release-checklist.md

@@ -123,16 +123,6 @@ $ node bundle.js
 Done in 1.00s.
 ```
 
-### Rebuild the Device Type Definition Schema
-
-Run the following command to update the device type definition validation schema:
-
-```nohighlight
-./manage.py buildschema --write
-```
-
-This will automatically update the schema file at `contrib/generated_schema.json`.
-
 ### Update & Compile Translations
 
 Updated language translations should be pulled from [Transifex](https://app.transifex.com/netbox-community/netbox/dashboard/) and re-compiled for each new release. First, retrieve any updated translation files using the Transifex CLI client:
@@ -160,6 +150,24 @@ Then, compile these portable (`.po`) files for use in the application:
 !!! tip
     Put yourself in the shoes of the user when recording change notes. Focus on the effect that each change has for the end user, rather than the specific bits of code that were modified in a PR. Ensure that each message conveys meaning absent context of the initial feature request or bug report. Remember to include keywords or phrases (such as exception names) that can be easily searched.
 
+### Rebuild the Device Type Definition Schema
+
+Run the following command to update the device type definition validation schema:
+
+```nohighlight
+./manage.py buildschema --write
+```
+
+This will automatically update the schema file at `contrib/generated_schema.json`.
+
+### Update the OpenAPI Schema
+
+Update the static OpenAPI schema definition at `contrib/openapi.json` with the management command below. If the schema file is up-to-date, only the NetBox version will be changed.
+
+```nohighlight
+./manage.py spectacular --format openapi-json > ../contrib/openapi.json
+```
+
 ### Submit a Pull Request
 
 Commit the above changes and submit a pull request titled **"Release vX.Y.Z"** to merge the current release branch (e.g. `release-vX.Y.Z`) into `main`. Copy the documented release notes into the pull request's body.

scripts/verify-openapi.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+
+# This script checks for differences between the generated OpenAPI schema and the static definition
+# saved at contrib/openapi.json. If the two are not identical, the script returns an error.
+
+PROJECT_ROOT="$PWD"
+CMD="python $PROJECT_ROOT/netbox/manage.py spectacular --format openapi-json"
+SCHEMA_FILE="$PROJECT_ROOT/contrib/openapi.json"
+
+# Generate the OpenAPI schema & save it to a temporary file
+TEMP_FILE=$(mktemp)
+trap 'rm -f "$TEMP_FILE"' EXIT
+eval "$CMD > $TEMP_FILE"
+
+# Run a diff between the original & generated schemas
+if diff -u "$SCHEMA_FILE" "$TEMP_FILE"; then
+    echo "✅ No changes found."
+    exit 0
+else
+    echo "❌ Change(s) to OpenAPI schema detected."
+    exit 1
+fi