OpenAPI

Translate explanatory fields in OpenAPI 3.x YAML while retaining paths, operation identifiers, and references.

An OpenAPI document combines a machine-readable API contract with explanations for people using it. The yaml-openapi file handler selects title, description, and summary fields by their location in OpenAPI 3.x YAML. Paths, operation IDs, and references stay fixed.

Keep the API contract stable #

In this example, the operation keeps its identity while its explanation can change language:

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

The handler selects the title, summary, and response description. /orders, listOrders, and 1.0.0 remain unchanged. Selection also covers information fields, tag and external-documentation descriptions, path descriptions, and descriptive fields under recognized schema and operation containers.

Inspect object-valued examples and defaults in those containers. A nested property named title, description, or summary can also be selected even when it represents example payload data. Other schema values, such as ordinary enum strings and $ref values, are left unchanged.

The parser requires a YAML mapping with an openapi version beginning with 3.. Swagger 2.x, missing versions, and other versions are rejected. A JSON OpenAPI file is not selected merely because OpenAPI permits JSON; this handler's contract is YAML.

Reconstruction and reuse #

The current source defines the specification tree. Existing wording is matched using descriptive-field identity and occurrence, with operation identity contributing to alignment. Changed source descriptions become new translation work; unchanged matching fields can reuse target wording.

The YAML serializer reconstructs the document and can normalize formatting. Keep previous source and target specifications aligned, and inspect field movements or repeated descriptions that affect reuse.

Select the specification handler #

Explicitly select yaml-openapi for .yaml or .yml in CLI file configuration. The extension alone cannot distinguish an API specification from an application catalog. Generic YAML would select many more strings; Locale-root YAML has a different wrapper contract.

Use CLI configuration or GitHub for file selection and destination paths. CLI key-scoped translation is unavailable for OpenAPI.

Validate the contract and read the descriptions #

Validate the reconstructed document with your OpenAPI tooling and compare paths, operation IDs, references, required fields, and schema values with the source. Then read the rendered descriptions beside that contract. A response description that changes a condition or promise can mislead a developer even when the specification remains valid.