Fusionar definiciones de API

La fusión de referencias de API le permite combinar varias definiciones de API existentes en una única referencia de API fusionada. Esto es útil cuando la superficie de su API está repartida entre varios servicios o archivos, pero desea que los lectores consulten una referencia unificada.

El resultado fusionado se guarda como una referencia de API en borrador para que pueda revisarla antes de publicarla.


Fusionar referencias de API

Para crear una referencia de API fusionada:

  • En la navegación superior del editor, abra el menú de la sección.

  • Haga clic en + New API reference.

  • Elija Merge references.

  • (Opcional) Añada una Override API Reference.

  • Seleccione de la lista las referencias de API que desea fusionar (de la versión actual).

  • Establezca el orden de fusión con las flechas arriba y abajo situadas junto a cada referencia.

  • Haga clic en Merge. La referencia de API fusionada se creará en estado borrador.

Override API Reference

La Override API Reference es una definición OpenAPI opcional que tiene prioridad sobre todo lo demás en la fusión. Puede proporcionarse en formato JSON o YAML. Úsela para sobrescribir partes específicas del resultado fusionado, por ejemplo:

  • info (incluidos title, description y version)

  • Cualquier componente, esquema y definición de seguridad que desee que prevalezca en caso de conflicto

La versión de OpenAPI es obligatoria

La Override API Reference debe incluir la versión openapi. En la práctica, también se espera que info, description y version se sobrescriban aquí.

Ejemplo de Override API Reference

Esta sobrescritura establece el título y la versión de la API, y reemplaza el esquema de seguridad bearerAuth.

openapi: 3.0.3
info:
title: Merged API (Public)
description: Consolidated reference for all services.
version: 2026-03-01
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
security:
- bearerAuth: []
{
"openapi": "3.0.3",
"info": {
"title": "Merged API (Public)",
"description": "Consolidated reference for all services.",
"version": "2026-03-01"
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
}
},
"security": [
{ "bearerAuth": [] }
]
}

Orden de fusión y precedencia

Puede elegir entre las referencias de API que ya existen en la versión que está editando actualmente.

La precedencia se determina por el orden de la lista:

  • Las referencias que aparecen antes en la lista tienen prioridad.

  • Las referencias que aparecen después en la lista (número de orden mayor) sobrescriben a las anteriores cuando hay un conflicto.

Los conflictos se resuelven por nombre. Si el mismo nombre existe en varias referencias, las posteriores sobrescriben a las anteriores, por ejemplo:

  • Componentes

  • Esquemas

  • Esquemas de seguridad (y otros objetos con nombre relacionados con la seguridad)

Para cambiar la precedencia, use las flechas arriba y abajo junto a cada referencia de la lista.

Requisitos

  • Todas las definiciones de API de la fusión deben usar exactamente la misma versión de OpenAPI.


  Última actualización