APIkit for AsyncAPI モジュールでの Avro スキーマの実装と検証

APIkit for AsyncAPI では、メッセージの構造とエンコードを指定するための形式を定義するのに役立つデータシリアル化システムである、 Avro がサポートされています。このモジュールは、設計フェーズでのメッセージの構造を示します。APIkit for AsyncAPI では、Avro スキーマを使用したメッセージの DataSense もサポートされます。

スキーマ定義

Avro 仕様では、schemaFormat の値を application/vnd.apache.avro として指定することで、その形式を定義します。

Avro 仕様では、スキーマのインライン記述、または Avro 形式でスキーマを記述する外部ドキュメントの参照がサポートされています。

インライン定義

publish:
  summary: inform details about person
  operationId: lightMeasured
  message:
    schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
    payload:
      name: lightMeasured
      type: record
      fields:
        - name: lumens
          type: int
          example: 134
        - name: sentAt
          type: string
          logicalType: timestamp-millis
          10
          example: 1985-04-12T23:20:50.52Z

Avro フラグメントへの参照

channels:
 smartylighting.streetlights.1.0.event.{streetlightId}.monitor:
   publish:
     message:
       schemaFormat: application/vnd.apache.avro;version=1.9.0
       payload:
         $ref: /exchange_modules/83589b9b-6630-4c28-985d-174ee9172661/lumenschema/1.0.0/lumens.json'

lumens.json ファイルは、Avro スキーマの仕様を提供します。

{
  "type": "record",
  "name": "lightMeasured",
  "fields": [
    {"name": "lumens", "type": "int"},
    {"name": "sentAt", "type": {"type": "string", "logicalType": "timestamp-millis"}}
  ]
}

APIkit for AsyncAPI は、Avro メッセージがインラインで定義された非同期 API をサポートしています。APIkit for AsyncAPI は、Avro フラグメントを参照する API 仕様をサポートしていません。

Avro メッセージのエンコードと検証

Avro メッセージは、バイナリ形式またはテキスト (JSON) 形式でエンコードされます。仕様では、contentType または defaultContentType の値が提供されます。

APIkit for AsyncAPI は、テキスト (JSON) でエンコードされたメッセージを検証しますが、バイナリでエンコードされたメッセージは検証しません。