Programmatically catch breaking API changes
- Vorherrschende Sprache
- Keine Sprachdaten
- Sterne
- 3
- Forks
- 0
- PR-Merge-Kennzahlen
- Keine gemergten PRs in 30 T.
Beschreibung
Breaking changes to the API, such as a new status code or differed type, go undetected by our tests. The API is validated by the `codersdk.Client` which is updated alongside the server. So no warnings are raised when api breaking changes occur.
This blind spot leads to us expecting engineers to manually catch breaking API changes in the PR review process.
We should identify these programmatically _without_ adding a chunk of cross-version tests, leveraging something like [`swagger-diff`](https://swagger.io/blog/api-development/using-swagger-to-detect-breaking-api-changes/).
This recently caused a minor regression in [v2.14.0](https://github.com/coder/coder/releases/tag/v2.14.1), where a status code change slipped into our release.
This tool should catch:
- Success status code changes for existing apis: `// @Success 200`
- Removed routes: `// @Router`
- Removed params: `// @Param`
- Type differences on params and success **if fields are removed** (json adding fields is ok)
Beitragsleitfaden
Für dieses Repository ist kein Beitragsleitfaden indexiert
Rechercherichtung
Beginne damit zu prüfen, wie codersdk.Client und die API-Definitionen des Servers gemeinsam gepflegt werden, und bewerte anschließend swagger-diff oder ein ähnliches OpenAPI-Vergleichstool. Verwende die aufgeführten Beispiele als Akzeptanzkriterien: Erkenne Änderungen an Erfolgsstatuscodes, entfernte Routen oder Parameter sowie Breaking Changes an Typen, während hinzugefügte JSON-Felder zulässig bleiben. Bestätige, dass das Tool die Regression der Statuscodes in v2.14.0 erkennt.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- openapi
- Bereich
- api, backend-api-design
- Issue-Typ
- Feature
- Schwierigkeit
- 4/5
- Geschätzter Aufwand
- 3-5 Tage
- Aktivitätsstatus
- Veraltet
- Klarheit
- Größtenteils klar
- Anfängerfreundlichkeit
- 35/100