Test OpenAPI schema has no breaking changes (#979)

Modified `test_openapi` so that after it generates the current schema and runs the OpenAPI linter, it'll also check for breaking changes.

I'm adding this test because we can no longer break old versions of Zoo Design Studio. We should really never break the OpenAPI schema. If you find you need a breaking change, just make a new endpoint instead.

The new "check for breaking changes" test logic is pretty simple. It does this by:

1. Downloading the latest schema on `main` branch from GitHub
2. Reading this branch's schema from disk (written earlier in `test_openapi`)
3. Run `just breaking-api-changes`, which
4. compares the two schemae via the `openapi-changes` CLI tool. 
5. If there's a breaking change, that tool terminates with exit code 1 (and 0 i.e. OK if there's no changes, or only additive changes).

In my testing, this tool has much better understanding of OpenAPI than `oasdiff`, which the engine currently uses. For example, `oasdiff` thinks that adding a new optional field, or a field with a default value is a breaking change. That's wrong. `openapi-changes` correctly classifies those as additions, not breaking changes.

Author: adamchalmers

.github/workflows/ci.yml

@@ -40,6 +40,23 @@ jobs:
             verbose: true
             files: lcov.info
 
+    check-breaking-changes:
+      name: Check for breaking API changes
+      runs-on: ubuntu-latest-8-cores
+      steps:
+        - uses: actions/checkout@v4
+        - uses: taiki-e/install-action@just
+        - name: Install Rust
+          uses: dtolnay/rust-toolchain@stable
+        - uses: taiki-e/install-action@nextest
+        - name: Setup node
+          uses: actions/setup-node@v5
+        - name: Install openapi-changes
+          run: npm i -g @pb33f/openapi-changes
+        - uses: Swatinem/[email protected]
+        - name: Run just breaking-api-changes
+          run: just breaking-api-changes
+
     check-lint:
       name: Check lints
       runs-on: ubuntu-latest-8-cores

.gitignore

@@ -4,3 +4,5 @@
 .idea/
 flamegraph.svg
 perf.data
+**/.DS_Store
+modeling-cmds/openapi/old_api.json

.helix/languages.toml

@@ -0,0 +1,2 @@
+[language-server.rust-analyzer.config]
+cargo.features = "all"

Cargo.lock

@@ -18,7 +18,7 @@ test:
 
 # Regenerate OpenAPI spec
 redo-openapi:
-    EXPECTORATE=overwrite cargo nextest run --all-features -- test_openapi
+    EXPECTORATE=overwrite cargo nextest run --all-features --nocapture -E "test(test_openapi)"
 
 # Run unit tests, output coverage to `lcov.info`.
 test-with-coverage:
@@ -71,3 +71,8 @@ finish-release pkg:
     git tag kittycad-{{pkg}}-$version -m "kittycad-{{pkg}}-$version"
     git push --tags
     cargo publish -p kittycad-{{pkg}}
+
+# Other actions: changelog, checks, diff, summary
+breaking-api-changes action='summary':
+    just redo-openapi 
+    openapi-changes {{action}} --no-color -b modeling-cmds/openapi/old_api.json modeling-cmds/openapi/api.json

justfile

@@ -69,6 +69,7 @@ dropshot = { version = "0.16.4", default-features = false }
 expectorate = "1.1.0"
 openapi-lint = { git = "https://github.com/KittyCAD/openapi-lint", branch = "kittycad" }
 openapiv3 = "2.2.0"
+reqwest = "0.12.23"
 tokio = { version = "1.47.1", features = ["macros"] }
 
 [lints]

modeling-cmds/Cargo.toml

@@ -23,6 +23,10 @@ async fn test_openapi() {
     // Check for lint errors.
     let errors = openapi_lint::validate(&spec);
     assert!(errors.is_empty(), "{}", errors.join("\n\n"));
+
+    // Download the old schema, write it to disk.
+    let schema = download_openapi_schema("main").await;
+    std::fs::write("openapi/old_api.json", schema).unwrap();
 }
 
 fn example_server() -> Result<ApiDescription<()>, String> {
@@ -50,3 +54,10 @@ fn example_server() -> Result<ApiDescription<()>, String> {
 
     Ok(api)
 }
+
+async fn download_openapi_schema(branch: &str) -> String {
+    let file = "openapi/api.json";
+    let path =
+        format!("https://raw.githubusercontent.com/KittyCAD/modeling-api/refs/heads/{branch}/modeling-cmds/{file}");
+    reqwest::get(path).await.unwrap().text().await.unwrap()
+}