¿Cómo se pueden dividir las especificaciones OpenAPI en varios archivos?

¿Cómo se pueden dividir las especificaciones OpenAPI en varios archivos? #

Un único documento OpenAPI puede volverse inmanejable a medida que una API madura. Una API real con decenas de recursos, cientos de operaciones y esquemas compartidos puede generar un archivo YAML monolítico difícil de navegar, de revisar en pull requests y de mantener entre varios equipos. La solución es dividir la especificación OpenAPI en varios archivos mediante referencias $ref y, después, agruparlos de nuevo en un único documento resuelto para que lo consuman las herramientas. Este enfoque, conocido a menudo como estructura OpenAPI “multiarchivo” o “modular”, está ampliamente adoptado en el desarrollo profesional de API.

¿Por qué dividir los documentos OpenAPI? #

Mantenibilidad #

Los archivos OpenAPI monolíticos de gran tamaño son difíciles de editar. Una estructura modular permite que distintos miembros del equipo trabajen en diferentes partes de la API sin conflictos de merge constantes. Por ejemplo, un equipo puede encargarse de las definiciones de la ruta /orders mientras que otro se encarga de las rutas /users.

Reutilización #

Los esquemas que aparecen en varias operaciones, como una envoltura Pagination, un objeto Error o un esquema Address, se pueden definir una sola vez en un archivo compartido y referenciar desde múltiples ubicaciones sin duplicación.

Legibilidad #

Un archivo YAML de 3000 líneas es difícil de navegar. Una estructura modular con nombres de archivo significativos hace que la superficie de la API sea evidente de inmediato:

openapi.yaml           # root document
paths/
  users.yaml           # /users operations
  orders.yaml          # /orders operations
  products.yaml        # /products operations
schemas/
  User.yaml
  Order.yaml
  Product.yaml
  Error.yaml
parameters/
  common.yaml          # shared parameters (pagination, etc.)
responses/
  common.yaml          # shared responses (400, 401, 404, 500)

Gobernanza y responsabilidad #

En las organizaciones API-first (que priorizan la API), cada archivo puede pertenecer a equipos concretos. Las herramientas de revisión de código, como CODEOWNERS de GitHub, pueden garantizar que solo el equipo responsable apruebe los cambios en su parte de la API.

Uso de `$ref` para referencias a archivos externos #

La palabra clave $ref de OpenAPI (y de JSON Schema) admite referencias a archivos externos mediante rutas relativas o absolutas, además de anclas dentro del mismo documento. Una referencia a un archivo externo tiene este aspecto:

# openapi.yaml
paths:
  /users:
    $ref: './paths/users.yaml'
  /orders:
    $ref: './paths/orders.yaml'

components:
  schemas:
    User:
      $ref: './schemas/User.yaml'
    Order:
      $ref: './schemas/Order.yaml'
    Error:
      $ref: './schemas/Error.yaml'

Los archivos referenciados pueden contener a su vez referencias $ref a otros archivos, lo que permite una composición profunda.

Ejemplo de archivo de ruta #

# paths/users.yaml
get:
  summary: List users
  operationId: listUsers
  tags: [Users]
  parameters:
    - $ref: '../parameters/common.yaml#/parameters/PageSize'
    - $ref: '../parameters/common.yaml#/parameters/PageToken'
  responses:
    "200":
      description: A paginated list of users
      content:
        application/json:
          schema:
            $ref: '../schemas/UserList.yaml'
    "400":
      $ref: '../responses/common.yaml#/responses/BadRequest'
    "401":
      $ref: '../responses/common.yaml#/responses/Unauthorized'

post:
  summary: Create a user
  operationId: createUser
  tags: [Users]
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: '../schemas/CreateUserRequest.yaml'
  responses:
    "201":
      description: User created
      content:
        application/json:
          schema:
            $ref: '../schemas/User.yaml'

Referencias a fragmentos dentro de archivos externos #

$ref permite referenciar un nodo concreto dentro de un archivo externo mediante un fragmento de JSON Pointer:

$ref: './parameters/common.yaml#/parameters/PageSize'

Esto referencia la clave PageSize bajo parameters en common.yaml. Así, un único archivo compartido puede contener varias definiciones relacionadas.

Bundling: resolver en un único archivo #

Aunque las estructuras multiarchivo son excelentes para la edición, la mayoría de las herramientas de OpenAPI esperan un único documento totalmente resuelto. El proceso de combinar todos los archivos referenciados en uno solo se denomina bundling (empaquetado). El bundling puede hacerse de estas formas:

En línea (inline): reemplazando cada $ref por el contenido completo del objeto referenciado.
Desreferenciado (dereferenced): resolviendo todas las referencias $ref, pero manteniendo la estructura de components.
Empaquetado (bundled): reuniendo todas las referencias externas en components y reemplazando las referencias $ref externas por referencias $ref locales dentro del mismo archivo.

Herramientas de bundling #

Redocly CLI es la herramienta más popular para empaquetar documentos OpenAPI multiarchivo:

redocly bundle openapi.yaml -o openapi.bundled.yaml

Admite linting como parte del paso de bundling, de modo que detecta errores antes de que se propaguen.

swagger-cli (obsoleta, pero aún muy utilizada):

swagger-cli bundle openapi.yaml -o bundled.yaml -t yaml

@apidevtools/swagger-parser: una biblioteca de JavaScript para resolver, desreferenciar y validar documentos OpenAPI de forma programática:

import SwaggerParser from "@apidevtools/swagger-parser";

const api = await SwaggerParser.bundle("openapi.yaml");

openapi-typescript y muchas herramientas de generación pueden procesar documentos multiarchivo directamente, sin un paso de bundling independiente.

Estructura de directorios recomendada #

Una convención ampliamente adoptada para proyectos OpenAPI grandes:

api/
├── openapi.yaml                # Root document with info, servers, security
├── paths/
│   ├── users.yaml              # Operations for /users
│   ├── users_{id}.yaml         # Operations for /users/{id}
│   ├── orders.yaml
│   └── products.yaml
├── schemas/
│   ├── User.yaml
│   ├── Order.yaml
│   ├── Product.yaml
│   ├── CreateUserRequest.yaml
│   └── Error.yaml
├── parameters/
│   └── common.yaml             # Shared parameters
├── responses/
│   └── common.yaml             # Shared responses
└── examples/
    ├── UserExample.yaml
    └── OrderExample.yaml

El archivo raíz openapi.yaml sirve únicamente como punto de entrada y delega en los archivos de rutas y de componentes:

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    $ref: './paths/users.yaml'
  /users/{id}:
    $ref: './paths/users_{id}.yaml'
  /orders:
    $ref: './paths/orders.yaml'

Linting de documentos multiarchivo #

Spectral y Redocly CLI admiten el linting de documentos multiarchivo siguiendo las referencias $ref durante el análisis:

spectral lint openapi.yaml
redocly lint openapi.yaml

Ambas herramientas resuelven todas las referencias antes de aplicar las reglas, por lo que las comprobaciones de gobernanza se aplican a toda la superficie de la API, sin importar cómo esté dividida.

Buenas prácticas de control de versiones #

Al gestionar un proyecto OpenAPI multiarchivo en Git:

Usa pull requests para los cambios en los esquemas: los archivos de esquema individuales son lo bastante pequeños como para revisarse de forma significativa en el diff de una PR.
Configura CODEOWNERS: asigna la propiedad de los archivos de rutas a los equipos responsables de esos endpoints.
Usa un paso de bundling en CI: genera siempre el documento empaquetado y confírmalo (o publícalo) como artefacto de CI, para que los consumidores posteriores dispongan siempre de una versión estable y resuelta a la que hacer referencia.
Etiqueta las versiones: versiona el documento empaquetado con etiquetas de Git para permitir que los consumidores fijen una versión concreta.

Conclusión #

Dividir las especificaciones OpenAPI en varios archivos es una estrategia probada para gestionar la complejidad de los proyectos de API grandes. Al combinar las referencias externas $ref con una estructura de directorios bien organizada y un paso de bundling en el pipeline de compilación, los equipos obtienen las ventajas de la modularidad en la edición (reutilización, desarrollo en paralelo y revisiones de código centradas) sin sacrificar la compatibilidad con las herramientas. A medida que las API crecen, una estructura multiarchivo no es solo algo recomendable: es una práctica esencial para un desarrollo de API sostenible.

Última actualización: 29 de abril de 2026.