Der zuverlässige Weg, eine hier veröffentlichte API zu versionieren, ist ein Pfadsegment: baue deine breaking Change als neuen Endpunkt unter /v2/items, während /v1/items genau so weiterläuft wie immer. Beide sind wirklich separate Endpunkte mit eigenen Graphen, sodass Aufrufer der alten Version nie von Arbeit an der neuen betroffen sind, und du /v1 nach deinem eigenen Zeitplan abschalten kannst (sieh dir "Rate Limiting, CORS, und eingehende Anfragen authentifizieren" für die Deprecation und Sunset Einstellungen an, die dabei helfen).
Einrichtung
Gib beim Erstellen eines Endpunkts einfach einen Pfad, der mit einem Versionssegment beginnt, /v1/items, /v1/items/:id, und so weiter. Das Formular zur Endpunkterstellung zeigt einen Hinweis auf diese Konvention, falls dein Pfad noch nicht damit beginnt, es ist ein Vorschlag, keine Pflicht, viele APIs brauchen nie mehr als eine Version.
Was das für deine Docs tut
Dein generiertes OpenAPI Dokument (unter /openapi.json) gruppiert Endpunkte automatisch nach ihrem führenden Versionssegment als Tag, sodass /v1/... und /v2/... Endpunkte klar getrennt auf der gehosteten Docs Seite erscheinen, ohne dass du jeden Endpunkt von Hand taggen musst. Ein Endpunkt, dem du bereits eigene, explizite Tags gegeben hast, behält diese stattdessen.
Was das freie "Version" Feld stattdessen tut
Das Settings Panel eines Endpunkts hat auch ein separates, informatives Version Feld, es fügt einen X-API-Version Antwort Header hinzu und erscheint in der eigenen Versionsnummer des OpenAPI Dokuments, nützlich als Label, hat aber keinen Effekt auf das Routing. Der obige Pfadsegment Ansatz ist es, der tatsächlich bestimmt, welcher Graph läuft.