OpenAPI

Traduce los campos explicativos de los documentos YAML de OpenAPI 3.x sin alterar 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 utilizan. El controlador 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 identificadores de operación y las referencias permanecen intactos.

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:

yaml
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 retrieved

El controlador selecciona el título, el resumen y la descripción de la respuesta. /orders, listOrders y 1.0.0 permanecen 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 de esquemas y operaciones reconocidos.

Revisa los ejemplos y los valores predeterminados de tipo objeto en esos contenedores. También puede seleccionarse una propiedad anidada llamada title, description o summary, incluso cuando represente datos de una carga útil de ejemplo. Los demás valores del esquema, como las cadenas de enumeración habituales y los valores de $ref, se mantienen sin cambios.

El analizador requiere un mapa YAML con una versión de openapi que empiece por 3.. Se rechazan Swagger 2.x, los documentos sin versión y las demás versiones. Un archivo OpenAPI en JSON no se selecciona por el mero hecho de que OpenAPI admita JSON: este controlador trabaja con YAML por contrato.

Reconstrucción y reutilización #

El documento de origen actual define el árbol de la especificación. Los textos existentes se cotejan según la identidad y la aparición de cada campo descriptivo; la identidad de la operación también ayuda a establecer la correspondencia. Las descripciones de origen modificadas requieren nuevas traducciones; los campos coincidentes que no hayan cambiado 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 a la reutilización.

Selecciona el controlador 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 controlador genérico de YAML seleccionaría muchas más cadenas; YAML con idioma en la raíz exige una estructura envolvente distinta.

Usa 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 identificadores de operación, las referencias, los campos obligatorios y los valores del esquema con el documento de origen. Después, 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 inducir a error a quien desarrolla, aunque la especificación siga siendo válida.