La forma confiable de versionar una API publicada aquí es un segmento de ruta: construye tu cambio incompatible como un endpoint nuevo en /v2/items mientras /v1/items sigue funcionando exactamente como siempre. Ambos son endpoints genuinamente separados con sus propios grafos, así que los emisores de la versión antigua nunca se ven afectados por el trabajo en la nueva, y puedes retirar /v1 según tu propio calendario (consulta "Límite de velocidad, CORS, y autenticación de solicitudes entrantes" para los ajustes de Obsolescencia y Retirada que ayudan con eso).
Configurarlo
Al crear un endpoint, simplemente dale una ruta que empiece con un segmento de versión, /v1/items, /v1/items/:id, y así sucesivamente. El formulario de creación de endpoints muestra un recordatorio de esta convención si tu ruta no empieza ya con una, es una sugerencia, no un requisito, muchas APIs nunca necesitan más de una versión.
Qué hace esto por tu documentación
Tu documento OpenAPI generado (en /openapi.json) agrupa automáticamente los endpoints por su segmento de versión inicial como etiqueta, así que los endpoints /v1/... y /v2/... aparecen claramente separados en la página de documentación alojada, sin necesidad de etiquetar cada endpoint a mano. Un endpoint al que ya le has dado etiquetas propias explícitas conserva esas en su lugar.
Qué hace en cambio el campo libre de "versión"
El panel de Ajustes de un endpoint también tiene un campo versión separado e informativo, añade un encabezado de respuesta X-API-Version y aparece en el propio número de versión del documento OpenAPI, útil como etiqueta, pero no tiene efecto en el enrutamiento. El enfoque de segmento de ruta de arriba es lo que realmente determina qué grafo se ejecuta.