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

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

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

## 結論

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


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

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

https://github.com/ykhirao/qiita/tree/master/openapi

## 環境設定


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


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

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

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



## 作業の流れ




```terminal
# 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
```


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

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

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

```yaml
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だとこんな感じ

![スクリーンショット 2023-05-30 1.03.18.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/112929/47137501-7f7a-562b-7562-4a8bd5a995eb.png)



<details>
<summary>全文</summary>

```yaml
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
```

</details>


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

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

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

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

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


![スクリーンショット 2023-05-30 1.10.26.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/112929/82070543-cb7b-03c4-1686-271e091508e7.png)



<details>
<summary>全文</summary>

```yaml
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

```
</details>