1円でも得したいWebエンジニアの日常

クーポンだったりクレジットカードのポイントだったりを利用して1円でも得しつつ生活を便利にしていきたいWebエンジニアによるブログ。技術的な記事から商品レビューなど日常的なことまで。

OpenAPI Specification で Response の object の Key を固定値ではなくて可変にしたい場合(ハッシュを返したい場合)

f:id:yoshiki_utakata:20190411155855p:plain

はじめに

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

Dictionaries, Hashmaps, Associative Arrays | Swagger

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

Dictionary(Mao, 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?conuntries=en

{
  "en": "English",
}
GET /v1/languages?conuntries=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がcoutry, 値がlanguageとなるようなobject
    countryパラメータで指定されたcontryのみ結果が返ってくる
example:
  en: "English"
  fr: "French"

まとめ

  • レスポンスでハッシュを表現したい場合はadditionalProperties を使う!

Web API: The Good Parts

Web API: The Good Parts