データ生成規則

この機能は API Connect Enterprise as a Service

データ生成ルールは、要求のパラメーターおよびペイロードにデータを取り込むための値を選択する際に、自動テスターをガイドします。

API 定義および拡張機能から派生したデフォルト・ルールがありますが、自動テスターの一般的な正確性を向上させるため、またはその要求を特定のユース・ケースに合わせて調整するために、これらをオーバーライドしたい場合があります。そのためには、プロファイル構成の「データ・タイプ」セクションにカスタム・ルールを追加します。

データ生成ルールは、 データ生成プログラム を API 定義内のスキーマまたはタイプにバインドして、自動テスターが要求のデータをアセンブルしてそのスキーマまたはタイプを検出したときに、生成プログラムを使用してその時点で適切な値を提供するようにします。

データ生成プログラム

データ生成プログラム は、値の非終止シーケンスを記述し、自動テスターが生成プログラムを呼び出すたびに、そのシーケンスから次の値を取得します。

生成ルールの構文では、JSON スキーマからの用語が再使用されます。スキーマに対する暗黙の制約は、適合する値を生成する際に自動テスターをガイドするのに十分です。 API 定義で発生するこのような制約は、デフォルト・ルールの通知に役立ちます。

定数

定数ジェネレーターは、常に同じ値を返します。この値は、任意の単純タイプにすることができます。

const: 0

# ==> 0, 0, 0, ...

const: Thursday

# ==> "Thursday", "Thursday", "Thursday", ...

列挙

列挙ジェネレーターは、指定されたリストからランダムに選択された値を返します。これは任意の単純タイプにすることができます。

enum:
  - 0
  - 1
  - 2

# ==> 1, 0, 2, 0, ...

enum:
  - Thursday
  - Friday
  - Saturday

# ==> "Friday", "Saturday", "Saturday", ...

パターン

pattern ジェネレーターは、指定された正規表現に一致するストリング値を返します。

pattern: '[0-9]{3}'

# ==> "884", "924", "121", ...

pattern: '[a-z][a-z_]{0,15}'

# ==> "dbe", "kg_cfsv", "dhbfgbjxavmsaxq", ...

範囲

range ジェネレーターは、指定された範囲 (両端を含む) に均等に分散された数値を返します。

minimum: 0
maximum: 10

# ==> 10, 6, 8, ...

いずれかのエンドポイントが省略された場合、そのタイプの最も負の値または最も正の値がデフォルトとして使用されます。

minimum: 0

# ==> 10029625, 3162517758, 841054690, ...

セマンティック

セマンティック ・ジェネレーターは、事前定義されたセマンティック・カテゴリー (名前、住所、クレジット・カード番号など) に準拠する値を返します。カテゴリーのセットは、 API 拡張で許可されているものと同じです。

semantic: email

# ==> "herbertschaden@fahey.net", "emmyfarrell@cruickshank.com", "vilmaprohaska@zboncak.org", ...

semantic: first_name

# ==> "Antwan", "Connie", "Modesto", ...

リソース

リソース ・ジェネレーターは、既存のインスタンスのプールからランダムに選択された、特定のタイプのリソース・インスタンスの固有 ID である値を返します。インスタンスの ID は、 API 拡張で定義されたリソース・タイプの id_name プロパティーから取得され、そのタイプと形式はそれに応じて異なります。

resource: Customer

# ==> "e5537298-9041-47fc-b97e-c910d8f9d971", "f60521c8-2ccb-4036-a742-9f350271675f", "e5537298-9041-47fc-b97e-c910d8f9d971", ...

配列

配列生成プログラムは、再帰的に定義されたデータ生成プログラムから内容が取り込まれた配列値を返します。配列の長さは、 minItems と maxItems の間 (両端を含む) でランダムに選択されます。

items:
  pattern: '[0-9]{3}'
minItems: 3
maxItems: 3

# ==> ["770", "496", "219"], ["431", "895", "331"], ["864", "130", "204"], ...

items:
  enum:
    - 0
    - 1
minItems: 0
maxItems: 5

# ==> [], [1, 0, 1, 1], [0], ...

オブジェクト

オブジェクト 生成プログラムは、再帰的に定義された名前付きデータ生成プログラムからデータが取り込まれたプロパティーを持つオブジェクト値を返します。

properties:
  x:
    minimum: 0
    maximum: 100
  y:
    minimum: 0
    maximum: 100

# ==> {"x": 59, "y": 63}, {"x": 22, "y": 8}, {"x": 95, "y": 57}, ...

properties:
  code:
    pattern: '[0-9]{3}'
  language:
    enum:
      - en
      - fr
      - de

# ==> {"code": "452", "language": "fr"}, {"code": "504", "language": "en"}, {"code": "846", "language": "fr"}, ...

プロパティーがターゲット・スキーマによって必要とされない場合は、生成されたオブジェクトにそのプロパティーが含まれる頻度 ( 0.0 と 1.0の間) を指定する optional 属性でマークを付けることができます (ここで、0 は「なし」を意味し、1 は「常時」を意味します)。

properties:
  code:
    pattern: '[0-9]{3}'
  language:
    optional: 0.5
    enum:
      - en
      - fr
      - de
  tag:
    optional: 0.0

# ==> {"code": "452", "language": "fr"}, {"code": "504", "language": "en"}, {"code": "846"}, ...

選択

選択ジェネレーターは、指定されたデータ・ジェネレーターのリストからランダムに選択された値を返し、オプションの重みを使用して結果にバイアスをかけます。代替は、 array および object 生成プログラムを除く単純な生成プログラムでなければなりません。

choice:
  # bias the selection towards English
  - const: en
    weight: 5
  - const: fr
  - const: de

# ==> "en", "en", "en", ..., "de", "en", ...

choice:
  # normal values in the range 1-10
  - minimum: 1
    maximum: 10
    weight: 98
  # with a small percentage of outliers
  - const: 999
    weight: 2

# ==> 6, 3, 9, 1, ..., 999, 6, ...

データ生成規則

データ生成ルール は、API 定義で発生するスキーマにデータ生成プログラムをバインドして、自動テスターが API 呼び出しでそのスキーマの値を生成する方法を認識できるようにします。ルールは、プロファイル構成の「データ・タイプ」セクションで指定され、API 定義および拡張から派生したデフォルト・ルールをオーバーライドします。

スキーマは OpenAPI 仕様で広く使用されていますが、プロファイルでオーバーライド・ルールが許可されている自動テスターとの関連性が最も高い 3 つのキー・ロケーションがあります。

名前付きスキーマ
パラメーター
インライン要求本文

名前付きスキーマ

スキーマ・ルールは、 definitions (OpenAPI 2.0) または components/schema (OpenAPI 3.0) の下にある API 定義から名前付きスキーマにデータ生成プログラムを割り当てます。自動テスターは、指定されたスキーマが要求内に存在する場合は常に、指定された生成プログラムを使用します。

スキーマ規則は、プロファイル構成の「schemas」セクションの Datatypesの下に表示されます。

これは オーバーライド であるため、生成プログラムが元のスキーマに対して不完全である可能性があり、自動テスターはデフォルト規則を使用してギャップをカバーするようにフォールバックします。特に、スキーマがオブジェクト・タイプを記述している場合、ジェネレーターはオブジェクト・プロパティーのサブセットの名前のみを指定する必要があり、自動テスターはそれらのプロパティーのオーバーライドを適用しますが、残りのプロパティーにはデフォルト規則を使用します。

例えば、以下の名前付きスキーマが API 定義にあるとします。

Movie:
  type: object
  properties:
    title:
      type: string
    release_date:
      type: string
      format: date
    language:
      description: Two-letter ISO 639-1 language code
      type: string
      pattern: '[a-z]{2}'

スキーマから派生したデフォルト・ルールは、以下のような値を返します。

{
  "title": "mkLHM22Ohabb6YG4-wdZFUwxQa7dn",
  "release_date": "2018-09-14",
  "language": "jq"
}

title プロパティーおよび language プロパティーのデフォルト・ルールをオーバーライドすることで、これを詳細化できます。

Datatypes:
  schemas:
    Movie:
      properties:
        title:
          semantic: sentence
        language:
          enum:
            - en
            - fr
            - de

この規則は、オブジェクト生成プログラム (キーワード propertiesによって導入される) を Movie という名前のスキーマにバインドします。このスキーマは、 release_date のデフォルト規則と結合されて、以下のような値を返します。

{
  "title": "What dog everybody am myself hourly meeting how group over example her",
  "release_date": "2094-06-31",
  "language": "de"
}

パラメーター

パラメーター・ルールは、API 定義の paths の下にある操作内の名前付きパラメーターにデータ生成プログラムをバインドします。

パラメーター・ルールは、プロファイル構成の operations セクションの Datatypesの下に表示されます。

例えば、単一の呼び出しで返されるムービーの数を制限する API 定義で、 GET /movies に以下のパラメーター定義があるとします。

paths:
  /movies:
    get:
      parameters:
        - name: limit
          in: query
          description: Sets an upper bound on the number of movies returned
          schema:
            type: integer

この定義から派生したデフォルト・ルールは、整数範囲全体の値を返しますが、以下のように、より現実的な範囲を指定するプロファイル構成内のルールでこれをオーバーライドすることができます。場合によっては、外れ値を使用して検証ロジックを確認することもできます。

Datatypes:
  operations:
    /movies:
      get:
        parameters:
          - name: limit
            data:
              choice:
                - minimum: 1
                  maximum: 500
                  weight: 95
                - const: 0
                  weight: 3
                - const: 8000000
                  weight: 2

規則の形式は、元の定義の形式に従いますが、 schema の代わりにキーワード data を使用してデータ生成プログラムを導入します。

OpenAPI,、パラメータは名前と場所によって一意に識別される(そのため、同じ名前が例えばクエリとヘッダの両方で使用される可能性がある)。そのため、パラメータルールでは、曖昧さをなくすために必要な場合、 in プロパティをオプションとして許可する。この例では、照会パラメーターが limitという名前の唯一のパラメーターであるため、このパラメーターは使用されません。

自動テスターは、現在、タイプ query および path のパラメーター (および OpenAPI 2.0の body ) のみをサポートします。他のパラメーター・タイプにバインドされたルールは無視されます。

要求の本文

要求本体ルールは、データ生成プログラムを要求の本体にバインドします。この場合、対応するスキーマは、指定されたスキーマへの参照を介してではなく、API 定義の操作の一部として直接指定されます。

要求本体のルールは、プロファイル構成の operations セクションの Datatypesの下に表示されます。

例えば、 POST 要求へのペイロードを次のように定義するとします。

paths:
  /movies:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              allOf:
                - $ref: '#/components/schemas/Movie'
                - properties:
                    keywords:
                      type: array
                      items:
                        type: string

以下のルールは、新しいムービーに付加するためのいくつかの適切なキーワードを生成します (この場合、ムービー自体は前述のルールによってカバーされます)。

Datatypes:
  operations:
    /movies:
      post:
        requestBody:
          content:
            application/json:
              data:
                properties:
                  keywords:
                    # pick up to 3 items from the following list
                    items:
                      enum:
                        - avant-garde
                        - dystopia
                        - epic
                        - postmodern
                        - remake
                        - shootout
                    minItems: 0
                    maxItems: 3

パラメーター規則と同様に、形式は元の定義の形式に従いますが、 schemaの代わりに data を使用します。定義のスタイルは OpenAPI 3.0ですが、コンテンツ・タイプが整合している限り、ルールは OpenAPI 2.0 でも機能できます。あるいは、 OpenAPI 2.0 定義から、 body パラメーター・ルールを使用してペイロードを指定することもできますが、 3.0では機能しません。