¿Qué es el campo «externalDocs» en OpenAPI? #

Introducción #

La especificación OpenAPI (OAS) es un estándar para definir API que permite que tanto las personas como los equipos informáticos descubran y comprendan las capacidades de un servicio web sin acceso al código fuente ni a otra documentación. Una de las características clave de OpenAPI es su amplia capacidad de documentación. En este contexto, el campo de documentación externa (externalDocs) desempeña un papel importante. Este artículo explora el campo externalDocs de OpenAPI y detalla su propósito, su estructura y su uso.

Comprender OpenAPI #

Antes de entrar en los detalles del campo externalDocs, es esencial tener una comprensión básica de qué es OpenAPI. OpenAPI, conocido originalmente como Swagger, es un framework de código abierto para diseñar, crear, documentar y consumir servicios web RESTful. Al ceñirse a un formato estándar, OpenAPI proporciona una especificación detallada de los endpoints de la API, los modelos de datos y los mecanismos de autenticación, entre otros aspectos.

El objetivo principal de OpenAPI es facilitar la comprensión de las API y la interacción con ellas mediante un formato de especificación legible por máquinas. Esta especificación puede utilizarse después para generar documentación de la API, bibliotecas de cliente en distintos lenguajes de programación e incluso pruebas de la API.

Para obtener información más detallada sobre OpenAPI, puedes visitar el sitio web de la OpenAPI Initiative.

La función de externalDocs en OpenAPI #

En cualquier documentación de una API pueden darse situaciones en las que sea necesario hacer referencia a recursos externos. Por ejemplo, puede interesar citar guías detalladas, documentación adicional, tutoriales, términos de servicio o ejemplos de fuentes externas. El campo externalDocs de OpenAPI está diseñado precisamente para este fin.

¿Qué es externalDocs? #

El campo externalDocs es un medio para especificar documentación externa de una API o de cualquier componente individual dentro de la API. Permite a los proveedores de API enlazar a recursos externos y ofrecer a los usuarios contexto o detalles adicionales que no están incluidos en el propio documento OpenAPI.

Estructura de externalDocs #

El campo externalDocs es un objeto con dos propiedades opcionales:

• description: una descripción breve de la documentación de destino. Es una cadena legible por personas que aporta contexto sobre lo que representa el recurso externo.
• url: una cadena que contiene la URL de la documentación externa. Debe tener un formato de URL válido.

Ejemplos de uso #

El campo externalDocs puede aplicarse en varios niveles de un documento OpenAPI, como la especificación de nivel superior, las operaciones, los esquemas, etc. A continuación se muestran algunos escenarios de uso habituales:

1. Documentación de nivel superior #

Este es un ejemplo de externalDocs utilizado en el nivel superior de la especificación de una API:

openapi: 3.0.3
info:
  title: Sample API
  version: 1.0.0
externalDocs:
  description: Find more info here
  url: https://example.com/documentation

En este ejemplo, externalDocs ofrece un enlace a una página de documentación más detallada de toda la API.

2. Documentación a nivel de operación #

También puedes usar el campo externalDocs dentro de operaciones individuales para enlazar a recursos externos específicos relevantes para ese endpoint:

paths:
  /users:
    get:
      summary: Get a list of users
      externalDocs:
        description: More info on user retrieval
        url: https://example.com/user-retrieval
      responses:
        '200':
          description: A list of users

3. Documentación a nivel de esquema #

De forma similar, externalDocs puede aplicarse a los esquemas para enlazar a definiciones externas o a descripciones más detalladas de los modelos de datos utilizados:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
      externalDocs:
        description: Detailed schema for the User entity
        url: https://example.com/user-schema

Ventajas de usar externalDocs #

1. Modularidad: al usar externalDocs, puedes mantener tu documento OpenAPI conciso y fácil de mantener, y colocar las guías detalladas y la documentación extensa en un lugar externo.

2. Enlaces a recursos enriquecidos: externalDocs te permite enlazar de forma dinámica a diversos recursos, como tutoriales en línea, ejemplos de uso de la API, términos de servicio y acuerdos de privacidad, lo que hace que tu documentación sea más rica y fácil de usar.

3. Actualizaciones coherentes: la documentación externa puede actualizarse de forma independiente del archivo OpenAPI, lo que garantiza que los usuarios siempre tengan acceso a la información más actual.

Consideraciones #

Aunque externalDocs ofrece numerosas ventajas, conviene tener en cuenta algunas consideraciones:

• Gestión de las URL: asegúrate de que las URL proporcionadas en externalDocs se mantengan correctamente. Los enlaces rotos pueden frustrar a los usuarios y perjudicar la credibilidad de tu documentación.

• Adecuación al contexto: la documentación externa enlazada debe estar directamente relacionada con el contexto desde el que se enlaza. Los enlaces irrelevantes o excesivos pueden abrumar o confundir a los usuarios.

• Seguridad: asegúrate de que los enlaces externos sean seguros (mediante HTTPS) y apunten a recursos de confianza para evitar riesgos de seguridad.

Ejemplos reales #

Para aportar más contexto, veamos algunos usos reales del campo externalDocs en la documentación de API de código abierto.

API de GitHub #

En la documentación de la API REST de GitHub, externalDocs se utiliza para enlazar a guías detalladas y recursos adicionales. Por ejemplo, en algunos de sus endpoints ofrecen enlaces a su documentación más amplia o a ejemplos de uso.

API de Google #

Las API de Google, como las que ofrece Google Cloud, suelen incluir enlaces a documentación externa para ofrecer ejemplos y tutoriales completos. Hacen un uso extensivo de externalDocs para ayudar a los desarrolladores a comprender el contexto general y los patrones de uso de sus API.

Ejemplo de Swagger Petstore #

Swagger Petstore es un ejemplo mínimo muy popular que se utiliza para demostrar las funciones de OpenAPI. Utiliza externalDocs para enlazar a documentación adicional de la API de Petstore, lo que ayuda a los usuarios a explorar funciones avanzadas y novedades.

Conclusión #

El campo externalDocs de OpenAPI es una herramienta poderosa para crear documentación de API rica, modular y fácil de mantener. Al enlazar con criterio a recursos externos, los proveedores de API pueden ofrecer información completa que encaja a la perfección con la especificación concisa de las API. Comprender e implementar correctamente el campo externalDocs puede mejorar de forma notable la utilidad y la experiencia de usuario de la documentación de tu API.

Para obtener más información, puedes consultar la documentación de la especificación OpenAPI.

Al aprovechar externalDocs, no te limitas a describir tu API dentro del propio documento OpenAPI, sino que puedes extenderte a una gran variedad de recursos adicionales y ofrecer así una experiencia del desarrollador mucho más enriquecida.

Última actualización: 12 de junio de 2024.