はじめに

OpenAPのドキュメントの以下のページの訳的なブログです。

Dictionaries, Hashmaps, Associative Arrays

Dictionary, ハッシュマップ, 連想配列

Dictionary（Map, HashMap, 連想配列などとも呼ばれる）は、keyとvalueのペアである。Open API では key が string のものを Dictionary として定義している。Dictionary を定義するには、 type: object にして additionalProperties キーワード利用する。

additionalProperty とは

additionalProperty とは「定義されたキー以外にもプロパティが返ってくるよ」という意味である。本来の使い方は以下の通りである。

type: object
properties:
  id:
    type: string
  additionalProperties: true

このような書き方をした場合、この object は「id は返ってくるが、それ以外も何か返す可能性があるよ」の意味となる。逆に

type: object
properties:
  id:
    type: string
  additionalProperties: false

この場合は、「id 以外のものが返ってくることはない」の意味になる。additionalProperties のデフォルトはfalseだ。

additionalProperty を利用してDictionaryを書く

例えばこういうAPIがあったとする

GET /v1/languages?countries=<array>

サンプルリクエストとレスポンスはこうだ

GET /v1/languages?countries=en

{
  "en": "English",
}

GET /v1/languages?countries=en,fr

{
  "en": "English",
  "fr": "French"
}

このようにリクエストによって要素の数が変動するのだ。この場合はこう書くことになる。

type: object
additionalProperties:
  type: string

additionalProperties には true/false だけでなく type を書くことができる。これは、additionalProperties として返ってくる要素の値の型は（キーの型ではないので注意）すべて string だよということを示している。

このように書いた場合、exampleはこのような表記になる。

{
  "property1": string,
  "property2": string
}

非常に分かりづらいので、ここに example やdescriptionをを追記することもで補足説明することが望ましい。

type: object
additionalProperties:
  type: string
  description: |
    Keyがcountry, 値がlanguageとなるようなobject
    countryパラメータで指定されたcontryのみ結果が返ってくる
example:
  en: "English"
  fr: "French"