OpenAPI
Erläuternde Felder in OpenAPI-3.x-YAML übersetzen, ohne Pfade, Operations-IDs oder Referenzen zu verändern.
Ein OpenAPI-Dokument verbindet einen maschinenlesbaren API-Vertrag mit Erläuterungen für alle, die die API nutzen. Der Dateihandler yaml-openapi wählt die Felder title, description und summary anhand ihrer Position in OpenAPI-3.x-YAML aus. Pfade, Operations-IDs und Referenzen bleiben unverändert.
Den API-Vertrag stabil halten #
In diesem Beispiel behält die Operation ihre Identität, während sich ihre Erläuterung in andere Sprachen übersetzen lässt:
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 retrievedDer Handler wählt den Titel, die Zusammenfassung und die Antwortbeschreibung aus. /orders, listOrders und 1.0.0 bleiben unverändert. Die Auswahl umfasst außerdem Informationsfelder, Beschreibungen von Tags und externer Dokumentation, Pfadbeschreibungen sowie beschreibende Felder in erkannten Schema- und Operationscontainern.
Sehen Sie sich in diesen Containern die Beispiele und Standardwerte an, die als Objekte vorliegen. Auch eine verschachtelte Eigenschaft namens title, description oder summary kann ausgewählt werden, selbst wenn sie Nutzdaten eines Beispiels darstellt. Andere Schemawerte, etwa gewöhnliche Enum-Zeichenfolgen und $ref-Werte, bleiben unverändert.
Der Parser setzt ein YAML-Mapping mit einer openapi-Version voraus, die mit 3. beginnt. Swagger 2.x, fehlende Versionsangaben und andere Versionen werden abgelehnt. Eine OpenAPI-Datei im JSON-Format wird nicht allein deshalb ausgewählt, weil OpenAPI JSON zulässt: Dieser Handler setzt YAML voraus.
Rekonstruktion und Wiederverwendung #
Die aktuelle Quelle legt die Baumstruktur der Spezifikation fest. Vorhandene Formulierungen werden anhand der Identität und des Vorkommens beschreibender Felder zugeordnet. Dabei trägt auch die Identität der Operation zum Abgleich bei. Geänderte Quellbeschreibungen müssen neu übersetzt werden; für unveränderte, übereinstimmende Felder lassen sich vorhandene Formulierungen in der Zielsprache wiederverwenden.
Der YAML-Serialisierer rekonstruiert das Dokument und kann dabei die Formatierung vereinheitlichen. Halten Sie die bisherigen Quell- und Zielspezifikationen aufeinander abgestimmt und achten Sie auf verschobene Felder oder wiederholte Beschreibungen, die sich auf die Wiederverwendung auswirken.
Den Spezifikationshandler auswählen #
Wählen Sie in der CLI-Dateikonfiguration ausdrücklich yaml-openapi für .yaml oder .yml aus. Anhand der Dateiendung allein lässt sich eine API-Spezifikation nicht von einem Anwendungskatalog unterscheiden. Generisches YAML würde deutlich mehr Zeichenfolgen auswählen; YAML mit Sprachen auf der obersten Ebene stellt andere Anforderungen an die umgebende Struktur.
Nutzen Sie die CLI-Konfiguration oder GitHub für die Dateiauswahl und die Zielpfade. Die auf einzelne Schlüssel beschränkte Übersetzung per CLI ist für OpenAPI nicht verfügbar.
Den Vertrag validieren und die Beschreibungen lesen #
Validieren Sie das rekonstruierte Dokument mit Ihren OpenAPI-Werkzeugen und vergleichen Sie Pfade, Operations-IDs, Referenzen, Pflichtfelder und Schemawerte mit der Quelle. Lesen Sie anschließend die gerenderten Beschreibungen im Zusammenhang mit diesem Vertrag. Eine Antwortbeschreibung, die eine Bedingung oder Zusage verändert, kann Entwicklerinnen und Entwickler in die Irre führen, selbst wenn die Spezifikation weiterhin gültig ist.