A megbízható módja egy itt közzétett API verziózásának egy útvonalszegmens: építsd meg a nem visszafelé kompatibilis változtatásodat egy új végpontként a /v2/items en, amíg a /v1/items pontosan úgy fut tovább, ahogy mindig is. Mindkettő valóban külön végpont, saját gráffal, így a régi verzió hívóit sosem érinti az újon végzett munka, és a saját ütemterved szerint vonhatod ki a /v1 et (nézd meg a "Sebességkorlátozás, CORS, és a bejövő kérések azonosítása" cikket az Elavulás és Megszűnés beállításokért, amik ebben segítenek).
Beállítása
Egy végpont létrehozásakor egyszerűen adj neki egy verziószegmenssel kezdődő útvonalat, /v1/items, /v1/items/:id, és így tovább. A végpont létrehozási űrlap emlékeztet erre a konvencióra, ha az útvonalad még nem ilyennel kezdődik, ez egy javaslat, nem követelmény, rengeteg API nak sosem lesz szüksége egynél több verzióra.
Mit tesz ez a dokumentációddal
A generált OpenAPI dokumentumod (a /openapi.json on) automatikusan csoportosítja a végpontokat a vezető verziószegmensük szerint, mint tag, így a /v1/... és /v2/... végpontok jól elkülönítve jelennek meg a hosztolt dokumentációs oldalon, anélkül hogy minden végpontot kézzel kellene megcímkézned. Egy végpont, aminek már saját, explicit tag jei vannak, azokat megtartja helyette.
Mit tesz helyette a szabad szöveges "verzió" mező
Egy végpont Beállítások paneljén van egy külön, informatív verzió mező is, ami hozzáad egy X-API-Version válaszfejlécet, és megjelenik az OpenAPI dokumentum saját verziószámában, hasznos címkeként, de nincs hatása az útválasztásra. A fenti útvonalszegmens megközelítés az, ami valójában eldönti, melyik gráf fut le.