¿Qué es la sección `servers` en OpenAPI?

¿Qué es la sección `servers` en OpenAPI? #

OpenAPI, antes conocido como Swagger, es un estándar potente para definir API que proporciona un marco estructurado para crearlas, documentarlas y consumirlas. Uno de los componentes esenciales de un documento OpenAPI es la sección servers. En este artículo exploraremos la importancia, la estructura y las buenas prácticas de uso de la sección servers en tus especificaciones OpenAPI.

Comprender OpenAPI #

Para entender la sección servers, conviene tener una idea general de qué es OpenAPI. OpenAPI es una especificación que permite a los desarrolladores definir los endpoints, los parámetros, los métodos de autenticación y otros aspectos de una API en un formato legible por máquinas. Este formato se escribe normalmente en YAML o en JSON y puede utilizarse para generar automáticamente documentación interactiva de la API, SDK de cliente y esqueletos de servidor (server stubs).

La especificación OpenAPI es mantenida por la OpenAPI Initiative, una colaboración entre líderes del sector para estandarizar las descripciones de las API.

La función de la sección `servers` #

La sección servers de un documento OpenAPI especifica una o más URL de servidor para tu API. Es un arreglo (array) de objetos de servidor, donde cada objeto proporciona información sobre un servidor concreto disponible para la API. Esta sección es fundamental porque indica a los consumidores de la API dónde pueden acceder a los endpoints definidos en tu documento OpenAPI.

Estructura básica #

La estructura típica de la sección servers tiene este aspecto en formato YAML:

servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server

Elementos de la sección `servers` #

Cada objeto de servidor puede contener los siguientes campos:

url: (Obligatorio) la URL base de la API.
description: (Opcional) una breve descripción del servidor.
variables: (Opcional) un mapa de variables que se sustituyen en la plantilla de URL del servidor.

Veamos con más detalle cada uno de estos elementos.

URL #

El campo url es el nombre de host (y, posiblemente, el puerto y la ruta) donde se sirve la API. Es el elemento más importante, ya que dirige a los consumidores al punto de entrada de tu API. La URL también admite plantillas, lo que permite configuraciones más dinámicas.

servers:
  - url: https://{environment}.example.com/v1
    variables:
      environment:
        default: api
        enum:
          - api
          - staging-api
          - dev-api

En el ejemplo anterior, {environment} es una variable de plantilla que puede sustituirse por uno de los valores indicados en enum.

Descripción #

El campo description es un campo de texto opcional en el que puedes describir la finalidad o la función del servidor. Resulta especialmente útil cuando tienes varios servidores, como los de desarrollo, preproducción y producción.

servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server intended for QA testing

Una buena descripción ayuda a los consumidores a entender rápidamente el uso adecuado de cada servidor.

Variables #

El campo variables permite sustituir partes de la URL del servidor por valores de variables. Esto hace que las URL sean más dinámicas y flexibles. Cada variable puede tener los siguientes subcampos:

default: (Obligatorio) el valor por defecto de la variable.
enum: (Opcional) un arreglo (array) de valores de cadena para limitar las opciones de la variable.
description: (Opcional) una descripción de la variable.

Este es un ejemplo:

servers:
  - url: https://{environment}.example.com/v1
    description: Templated server URL
    variables:
      environment:
        default: api
        enum:
          - api
          - staging-api
          - dev-api
        description: The stage environment of the API

En este caso, puedes controlar a qué entorno apunta la URL cambiando el valor de la variable environment.

Importancia de la sección `servers` #

La sección servers no es solo una forma cómoda de enumerar varios endpoints; desempeña un papel esencial en el versionado de la API, la separación de entornos y la facilidad de las pruebas.

Versionado de la API #

Al especificar URL distintas para cada versión de tu API, puedes mantener la compatibilidad con versiones anteriores mientras desarrollas nuevas versiones. Esto te permite actualizar tu API de forma incremental sin interrumpir a los usuarios existentes.

servers:
  - url: https://api.example.com/v1
    description: Production server V1
  - url: https://api.example.com/v2
    description: Production server V2

Separación de entornos #

Las API suelen tener distintos entornos, como desarrollo, preproducción, QA y producción. Cada uno de ellos puede representarse en la sección servers, lo que establece una distinción clara entre ellos.

servers:
  - url: https://dev-api.example.com/v1
    description: Development server
  - url: https://qa-api.example.com/v1
    description: QA server for testing
  - url: https://api.example.com/v1
    description: Production server

Facilidad de las pruebas #

Disponer de varias URL de servidor facilita las pruebas y la experimentación. Los consumidores de la API pueden cambiar de entorno sin modificar la lógica principal de sus aplicaciones.

Buenas prácticas #

Al redactar tu sección servers, ten en cuenta las siguientes buenas prácticas:

Claridad y documentación: incluye siempre un description para cada servidor que indique claramente su finalidad.
Uso prudente de las variables: aprovecha eficazmente las plantillas de URL para reducir la redundancia y facilitar la gestión de las URL.
Coherencia: sigue una convención de nomenclatura coherente en tus URL y descripciones en los distintos entornos y versiones.
Seguridad: asegúrate de no exponer información sensible en la sección servers, especialmente en documentos OpenAPI de acceso público.
Mantenlo actualizado: actualiza periódicamente tu documento OpenAPI para reflejar cualquier cambio en las URL de tus servidores o en los endpoints de tu API.

Herramientas y recursos #

Puedes aprovechar mejor la sección servers con diversas herramientas y plataformas:

Swagger Editor: un editor en línea para diseñar, documentar y probar especificaciones OpenAPI.
Postman: una herramienta versátil para probar API que permite importar y utilizar especificaciones OpenAPI.
OpenAPI Generator: una herramienta completa para generar SDK de cliente, esqueletos de servidor y documentación de la API a partir de especificaciones OpenAPI.

Estas herramientas simplifican el trabajo con especificaciones OpenAPI y ayudan a garantizar que tu sección servers se implemente y se utilice correctamente.

Conclusión #

La sección servers de OpenAPI es un componente fundamental que especifica dónde está alojada tu API. Es esencial para el versionado, la separación de entornos y para facilitar las pruebas y el consumo de tu API. Si estructuras y documentas con cuidado la sección servers, puedes conseguir que tu API sea más robusta, versátil y fácil de usar.

Utiliza las herramientas y las buenas prácticas descritas en este artículo para sacar el máximo partido a la sección servers en tus especificaciones OpenAPI y lograr un desarrollo y un consumo de API más eficientes. Para obtener más información sobre la especificación OpenAPI, consulta la documentación de OpenAPI oficial.

¡Feliz documentación de tus API!

Última actualización: 21 de mayo de 2024.

¿Qué es la sección servers en OpenAPI? #