Simple Answer

simpleanser

Swaggerの記載

Swagger

バージョン

現在

  • swagger 2.0
  • openapi 3.0(swagger 3.0)

があるが、「openapi 3.0」がよい。「openapi 3.0」から「oneOf」属性がサポートになっており、「いづれかひとつ」を表現できるようになっている。

参照：oneOf, anyOf, allOf, not

example、examplesでcomponents（定義）を参照する方法

components:
  examples:
    XXXX:

に定義する必要あり。（components/schemas等ではなく、components/examplesに定義する）

content:
  application/json:
    schema:
      $ref: '#/components/schemas/MyObject'
    examples:
      objectExample:
        $ref: '#/components/examples/objectExample'
...
components:
  examples:
    objectExample:
      value:
        id: 1
        name: new object
      summary: A sample object

参照：Adding Examples

objectでKeyを固定値ではなく可変にしたい場合はadditionalPropertiesを使用する

下記のようにadditionalPropertiesを使用する。

type: object
additionalProperties:
    type: string

参照：Dictionaries, Hashmaps, Associative Arrays

参照：OpenAPI Specification で Response の object で Key を固定値ではなくて可変にしたい場合（HashMap を返したい場合） - 猫でもわかるWebプログラミングと副業

いろんなサイトリンク

参考：本当に使ってよかったOpenAPI (Swagger) ツール | フューチャー技術ブログ

事例：Build, Collaborate & Integrate APIs | SwaggerHub

参考：CRUDでプロパティが変わるモデルをOpenAPIで書くときの定義分割 | Insight Technology

データ型：OpenAPI Specification 入門 - galife