El significado del atributo info.version en OpenAPI #
OpenAPI, antes conocido como Swagger, es una especificación para definir API. Uno de los componentes clave de un documento OpenAPI es el objeto info, que contiene metadatos sobre la API. Entre los distintos campos del objeto info, el atributo version desempeña un papel fundamental. Este artículo profundiza en el significado del atributo info.version, en las buenas prácticas para mantener las versiones de los documentos de definición de OpenAPI y en su impacto en el desarrollo y la documentación de API.
Cómo entender el atributo info.version #
El atributo info.version de un documento OpenAPI especifica la versión del propio documento de definición de OpenAPI. Esta versión es un valor de tipo cadena que, por lo general, sigue los principios del versionado semántico (por ejemplo, “1.0.0”). Es importante tener en cuenta que el atributo info.version no se refiere a la versión de la API que se describe, sino a la versión del documento que describe la API.
Ejemplo del atributo info.version #
A continuación se muestra un fragmento de un documento OpenAPI con el atributo info.version:
openapi: 3.0.1
info:
title: Sample API
description: A sample API to illustrate the info.version attribute
version: 1.0.0
paths:
/sample:
get:
summary: Sample endpoint
responses:
'200':
description: Successful response
En este ejemplo, el atributo info.version tiene el valor “1.0.0”, lo que indica la versión del documento de definición de OpenAPI de la Sample API.
Importancia del atributo info.version #
El atributo info.version es fundamental por varias razones:
- Gestión de documentos: ayuda a gestionar las distintas versiones del documento de definición de OpenAPI, lo que facilita el seguimiento de cambios y actualizaciones.
- Sincronización de clientes: garantiza que los clientes y los servidores usen la versión correcta de la especificación de la API, evitando posibles incompatibilidades.
- Seguimiento de cambios: facilita el seguimiento de cambios y el control de versiones, lo que permite a los desarrolladores comprender la evolución de la definición de la API a lo largo del tiempo.
- Coherencia: proporciona una referencia coherente para la versión específica de la documentación de la API que se está utilizando.
Buenas prácticas para mantener las versiones de las definiciones de OpenAPI #
Empieza con un versionado claro #
Comienza la documentación de tu API con una estrategia de versionado clara para la definición de OpenAPI. Decide si usarás el versionado semántico (SemVer) u otro esquema de versionado, y aplícalo de forma coherente durante todo el ciclo de vida de la API.
Documenta los cambios de versión #
Mantén un registro detallado de los cambios realizados en cada versión de la definición de OpenAPI. Esta documentación debe incluir las nuevas funciones, las mejoras, las correcciones de errores y cualquier cambio incompatible.
Versionado semántico #
El versionado semántico (SemVer) es un esquema de versionado ampliamente adoptado que utiliza un número de versión de tres partes: MAJOR.MINOR.PATCH. Cada parte transmite información específica sobre los cambios en la definición de OpenAPI.
Formato SemVer #
- MAJOR: se incrementa cuando hay cambios significativos que pueden incluir modificaciones incompatibles con versiones anteriores de la definición de la API.
- MINOR: se incrementa cuando se añaden funciones o se introducen mejoras compatibles con versiones anteriores de la definición de la API.
- PATCH: se incrementa cuando se corrigen errores o se hacen correcciones de documentación compatibles con versiones anteriores.
Ejemplo #
- 1.0.0: versión inicial de la definición de OpenAPI.
- 1.1.0: se añadieron nuevos endpoints de forma compatible con versiones anteriores.
- 1.1.1: se corrigió un error menor o se hizo una corrección de documentación sin afectar el funcionamiento de la API.
Usa sistemas de control de versiones #
Usa sistemas de control de versiones (VCS), como Git, para gestionar los cambios en el documento de definición de OpenAPI. El control de versiones te permite hacer un seguimiento de los cambios, volver a versiones anteriores y colaborar de manera eficaz con otros desarrolladores.
Versión en la URL o en los encabezados #
Mientras que el atributo info.version gestiona la versión del documento de definición de OpenAPI, el versionado de la propia API puede abordarse de otra forma. Entre las prácticas habituales se incluyen:
- Versionado en la URL: incluir la versión de la API en la ruta de la URL (por ejemplo,
/v1/resource). - Versionado en los encabezados: usar encabezados HTTP para especificar la versión de la API (por ejemplo,
Accept: application/vnd.example.v1+json).
Impacto del atributo info.version en el desarrollo #
Bibliotecas de cliente #
El atributo info.version ayuda a generar bibliotecas de cliente específicas para una versión concreta del documento de definición de OpenAPI. Esto garantiza que el código de cliente sea compatible con la versión correcta de la especificación de la API.
Documentación #
El atributo info.version es fundamental para generar documentación de API precisa y específica de cada versión. Herramientas de documentación como Redoc y Swagger UI usan este atributo para mostrar la información de versión y organizar las referencias de la API.
Pruebas y validación #
El versionado desempeña un papel importante en las pruebas y la validación. Al especificar info.version, los desarrolladores pueden escribir pruebas dirigidas a versiones concretas de la definición de OpenAPI, lo que garantiza que los cambios en una versión no rompan otra por accidente.
Avisos de obsolescencia #
El atributo info.version puede usarse junto con otras funciones de OpenAPI para ofrecer avisos de obsolescencia. Por ejemplo, marcar un endpoint como obsoleto en la documentación ayuda a los usuarios a prepararse para cambios futuros.
paths:
/old-endpoint:
get:
summary: Deprecated endpoint
deprecated: true
responses:
'200':
description: Successful response
Conclusión #
El atributo info.version de OpenAPI es un componente esencial que facilita la gestión eficaz de las versiones de las definiciones de OpenAPI. Al comprender su significado y seguir las buenas prácticas para mantener una documentación versionada, los desarrolladores de API pueden asegurarse de que sus definiciones sean sólidas, mantenibles y fáciles de usar.
Para profundizar y conocer herramientas relacionadas con OpenAPI y el versionado de API, consulta los siguientes recursos:
Al aprovechar el atributo info.version y aplicar las buenas prácticas, puedes crear y mantener definiciones de OpenAPI que no solo sean potentes y flexibles, sino también fáciles de usar y de mantener.
Última actualización: 05 de junio de 2024.