OpenAPI (Swagger)で配列レスポンスを記述する

配列の書き方難しいですよね。

結論

items というキーワードが重要！

keywords:
  type: array
  description: 最大10件のキーワードを指定できます
  items:
    type: string

詳細はこのレポジトリに記載してます。

環境設定

自分がOpenApiを記述するときの環境はnpmだけでやります。

フォルダ構成はこんな感じ

yk@yk openapi % tree
.
├── README.md
├── openapi.yaml
└── redoc-static.html

すぐに確認できるようにredocでドキュメント生成して確認してます。

作業の流れ

# openapi.yamlに記述する
$ vim openapi.yaml

# redocを生成しredoc-static.html を開く
$ npx @redocly/cli build-docs openapi.yaml

# for mac. 生成と開くのを同時にするコマンド
$ npx @redocly/cli build-docs openapi.yaml && open redoc-static.html

オブジェクトな配列を返すとき

{
  "ok": true,
  "products": [
    {
      "title": "MacBook",
      "url": "https://example.com"
    }
  ]
}

重要な部分だけ、productsという配列を返すとき

products:
  type: array
  description: 最大10件返します
  items:
    type: object
    properties:
      title:
        type: string
        description: 商品名
        example: MacBook
      url:
        type: string
        description: 商品のURL
        example: https://example.com

redocだとこんな感じ

全文

paths:
  '/':
    get:
      description: キーワード指定1つ
      operationId: Get by 1 KeyWord
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - keyword
              properties:
                keyword:
                  type: string
                  example: 'パソコン'
                  description: 適当なキーワードを入力してください
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                    description: ここは常にTrueを返します
                  products:
                    type: array
                    description: 最大10件返します
                    items:
                      type: object
                      properties:
                        title:
                          type: string
                          description: 商品名
                          example: MacBook
                        url:
                          type: string
                          description: 商品のURL
                          example: https://example.com

ストリングな配列をpostするとき

以下のようなbodyを送信する場合

{
  "keywords": [
    "パソコン",
    "マウス",
    "キーボード"
  ]
}

keywordsは type: array をうけてexampleを指定するとredocでいい感じになります

requestBody:
  content:
    application/json:
      schema:
        type: object
        required:
          - keywords
        properties:
          keywords:
            type: array
            description: 最大10件のキーワードを指定できます
            items:
              type: string
            example:
              - パソコン
              - マウス
              - キーボード

全文

paths:
  '/items':
    get:
      description: キーワード指定複数
      operationId: Get
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - keywords
              properties:
                keywords:
                  type: array
                  description: 最大10件のキーワードを指定できます
                  example:
                    - パソコン
                    - マウス
                    - キーボード
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                    description: ここは常にTrueを返します
                  products:
                    type: array
                    description: 最大10件返します
                    items:
                      type: object
                      properties:
                        title:
                          type: string
                          description: 商品名
                          example: MacBook
                        url:
                          type: string
                          description: 商品のURL
                          example: https://example.com