# frontend audience: asset ドメイン (ひな形)
#
# このファイルは docs/openapi/frontend/openapi.yaml から $ref で参照される断片であり、
# 単体では有効な OpenAPI ドキュメントではない(openapi/info を持たない)。
# 横断的関心事(エラー型)は ../problem.yaml を $ref で参照する。
#
# --- x-ix-changes の使い方 ---
# Javadocの @since 相当の独自拡張。version はこのドキュメント(frontend/openapi.yaml)の
# info.version の座標系で書く。
#   kind: added      … 新規追加
#   kind: changed    … 仕様変更(note必須)
#   kind: deprecated … 非推奨(note必須。OAS標準の deprecated: true も併記される)
# 例: x-ix-changes: [{ kind: added, version: "0.1.0" }]
# バンドル時に description へのMarkdown注記や、operationへの x-badges(一覧で見つけやすいバッジ)に
# 自動変換される(property/parameterはdescription注記のみ、operationはバッジも付く)。
# 詳細: docs/openapi/policy.md の「バージョン注記と非推奨」
#
# TODO: asset チームで、エンドポイント・スキーマの詳細を実装に合わせて更新すること。
# ここでは docs/openapi/policy.md の構成方針を示すためのひな形として最小限の内容のみ用意している。

paths:
  /api/v1/asset/aircrafts:
    get:
      operationId: listAircrafts
      summary: 機体一覧を取得する
      description: 管理する機体の一覧を取得し返却する
      tags: [Asset]
      x-ix-changes: [{ kind: added, version: "0.1.0" }]
      # TODO: 絞り込み条件などのクエリパラメータを定義する
      responses:
        "200":
          description: 機体一覧
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Aircraft"
        "4XX":
          description: リクエストエラー
          content:
            application/problem+json:
              schema:
                $ref: "../problem.yaml#/components/schemas/ProblemDetail"

components:
  schemas:
    # TODO: 実際のフィールドに置き換える。ここではひな形として最小限のプロパティのみ用意している
    Aircraft:
      type: object
      required: [id]
      properties:
        id:
          type: string
          format: uuid
          description: 機体ID
        # TODO: name, serialNumber, model などの実フィールドを追加する