ci: add API drift check on openapi.json#215
Open
infracore wants to merge 1 commit intodiscourse:mainfrom
Open
Conversation
Adds .github/workflows/api-schema-check.yml. Runs a structural diff on openapi.json against the PR base on every change, posts a comment when it sees a breaking change. Advisory-only; no fail-on, no required check. Sits next to validate_pr.yml: swagger-validator-v2 covers structural validity, this covers semantic drift (e.g. silent field renames in the response shape that pass structural validation but break SDK consumers). Concrete motivating finding: between commits c8d216f and 8361012, four field renames landed in POST /tag_groups.json 200 response (tag_names→tags, parent_tag_name→parent_tag) — both pairs structurally valid OpenAPI in both versions. Action pinned by commit SHA (afa76ce3...) rather than floating tag.
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Optional advisory CI check for semantic drift in
openapi.jsonPosting this as a small optional addition to sit alongside
validate_pr.yml. The swagger-validator step there catches structural problems; this one would catch the class of change where the document stays valid OpenAPI but the response shape moves under SDK consumers.Concretely, between commits c8d216f (early January) and 8361012 (April 23) four field renames landed in the response of
POST /tag_groups.json:tag_namesremoved; replaced withtagsparent_tag_nameremoved; replaced withparent_tagBoth pairs validate cleanly in OpenAPI 3.1.0, so they parsed fine through
validate_pr.yml. A plugin or SDK consumer readingtag_namesagainst the new spec would silently getundefinedfrom that point forward.What this PR adds
A single workflow file (
.github/workflows/api-schema-check.yml) that runs a structural diff onopenapi.jsonagainst the PR base and posts a comment if it flags a breaking change. Advisory-only: nofail-on, no required check, doesn't block any auto-PR. The Action is pinned by commit SHA rather than a floating tag.If the shape isn't useful or the scope is wrong, happy to revise or close.