OpenAPI
Traduce los campos explicativos de archivos YAML de OpenAPI 3.x sin modificar las rutas, los identificadores de operación ni las referencias.
Un documento OpenAPI combina un contrato de API legible por máquinas con explicaciones para quienes lo usan. El manejador de archivos yaml-openapi selecciona los campos title, description y summary según su ubicación en el YAML de OpenAPI 3.x. Las rutas, los ID de operación y las referencias se mantienen sin cambios.
Mantén estable el contrato de la API #
En este ejemplo, la operación conserva su identidad, pero su explicación puede cambiar de idioma:
openapi: 3.0.3
info:
title: Order service
version: 1.0.0
paths:
/orders:
get:
operationId: listOrders
summary: List your orders
responses:
"200":
description: Orders retrievedEl manejador selecciona el título, el resumen y la descripción de la respuesta. /orders, listOrders y 1.0.0 se mantienen sin cambios. La selección también abarca los campos de información, las descripciones de etiquetas y de documentación externa, las descripciones de rutas y los campos descriptivos dentro de los contenedores reconocidos de esquemas y operaciones.
Revisa los ejemplos y los valores predeterminados de esos contenedores cuyo valor sea un objeto. También se puede seleccionar una propiedad anidada llamada title, description o summary, incluso si representa datos de una carga útil de ejemplo. Los demás valores del esquema, como las cadenas comunes de enumeración y los valores de $ref, se mantienen sin cambios.
El analizador requiere un mapeo YAML con una versión de openapi que comience con 3.. Se rechazan Swagger 2.x, los documentos sin versión y las demás versiones. Un archivo OpenAPI en JSON no se selecciona solo porque OpenAPI admita JSON; el contrato de este manejador exige YAML.
Reconstrucción y reutilización #
El archivo de origen actual define el árbol de la especificación. El texto existente se vincula según la identidad de cada campo descriptivo y el orden en que aparece; la identidad de la operación también contribuye a la alineación. Las descripciones que cambian en el origen requieren nuevas traducciones; los campos coincidentes que no cambian pueden reutilizar el texto de destino.
El serializador YAML reconstruye el documento y puede normalizar el formato. Mantén alineadas las especificaciones anteriores de origen y destino, y revisa los cambios de ubicación de los campos o las descripciones repetidas que afecten la reutilización.
Selecciona el manejador de especificaciones #
Selecciona explícitamente yaml-openapi para .yaml o .yml en la configuración de archivos de la CLI. La extensión por sí sola no permite distinguir una especificación de API de un catálogo de una aplicación. El manejador genérico de YAML seleccionaría muchas más cadenas; YAML con idioma en la raíz tiene un contrato distinto para su estructura contenedora.
Usa la configuración de la CLI o GitHub para seleccionar archivos y definir las rutas de destino. La traducción limitada a claves específicas mediante la CLI no está disponible para OpenAPI.
Valida el contrato y lee las descripciones #
Valida el documento reconstruido con tus herramientas de OpenAPI y compara las rutas, los ID de operación, las referencias, los campos obligatorios y los valores del esquema con el documento de origen. Luego lee las descripciones tal como se muestran junto con ese contrato. Una descripción de respuesta que cambie una condición o una promesa puede confundir a quien desarrolla, incluso si la especificación sigue siendo válida.