OpenAPI

パス、オペレーション識別子、参照をそのままに、OpenAPI 3.x の YAML 内の説明フィールドを翻訳します。

OpenAPI ドキュメントには、機械が読み取れる API 契約と、利用者に向けた説明がまとめられています。yaml-openapi ファイルハンドラーは、OpenAPI 3.x の YAML 内での位置に基づき、title、description、summary の各フィールドを選択します。パス、オペレーション ID、参照は変更しません。

API 契約を維持する #

この例では、オペレーションの識別情報を維持したまま、説明の言語を切り替えられます。

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

ハンドラーは、タイトル、概要、レスポンスの説明を選択します。/orders、listOrders、1.0.0 は変更しません。このほか、情報フィールド、タグや外部ドキュメントの説明、パスの説明、ハンドラーが認識するスキーマやオペレーションのコンテナー内にある説明フィールドも選択対象です。

これらのコンテナー内では、値がオブジェクトになっているサンプルや既定値を確認してください。入れ子になったプロパティの名前が title、description、summary の場合、サンプルのペイロードデータであっても選択されることがあります。通常の列挙値の文字列や $ref の値など、その他のスキーマ値は変更しません。

パーサーで処理するには、openapi のバージョンが 3. で始まる YAML マッピングが必要です。Swagger 2.x、バージョン指定がないもの、それ以外のバージョンは受け付けません。OpenAPI が JSON に対応していても、JSON 形式の OpenAPI ファイルが選択されるわけではありません。このハンドラーが扱う形式は YAML です。

再構築と再利用 #

仕様のツリー構造は、現在のソースによって決まります。既存の文言は、説明フィールドの識別情報と出現箇所に基づいて照合され、オペレーションの識別情報も対応付けに使われます。ソースで変更された説明は新たな翻訳対象となり、変更がなく一致するフィールドでは、既存の翻訳を再利用できます。

YAML シリアライザーはドキュメントを再構築し、その際に書式を正規化することがあります。以前のソース仕様と翻訳先の仕様の対応を保ち、再利用に影響するフィールドの移動や説明の重複を確認してください。

仕様用ハンドラーを選択する #

CLI のファイル設定で、.yaml または .yml に対して yaml-openapi を明示的に選択してください。拡張子だけでは、API 仕様とアプリケーションのカタログを区別できません。汎用の YAML では、選択される文字列が大幅に増えます。ロケールをルートとする YAML は、外側の構造に関する要件が異なります。

ファイルの選択と出力先パスの指定には、CLI 設定または GitHub を使用してください。OpenAPI では、CLI によるキー単位の翻訳は利用できません。

契約を検証し、説明を確認する #

お使いの OpenAPI ツールで再構築後のドキュメントを検証し、パス、オペレーション ID、参照、必須フィールド、スキーマ値をソースと比較してください。そのうえで、表示された説明を契約と照らし合わせて読んでください。レスポンスの説明で条件や保証内容が変わると、仕様自体は有効でも、開発者の誤解を招くおそれがあります。