概要

laravel-openapiのスキーマ定義時の書き方をまとめる。

書き方

オブジェクトの中に単一のキー: 値

下記のようなスキーマを定義したい。
```
{
  "key_1": "hoge"
}
```

下記の様にスキーマクラスで定義する。

public function build(): SchemaContract
{
    return Schema::object('UserUpdateOkResponse')
        ->properties(
            Schema::string('key_1')
                ->description('key_1に紐づく文字列')
                ->example('hoge'),
        );
}

オブジェクトの中に複数のキー: 値

下記のようなスキーマを定義したい。

{
  "key_1": "hoge",
  "key_2": "fuga",
}

下記の様にスキーマクラスで定義する。

public function build(): SchemaContract
{
    return Schema::object('UserUpdateOkResponse')
        ->properties(
            Schema::string('key_1')
                ->description('key_1に紐づく文字列')
                ->example('hoge'),
            Schema::string('key_2')
                ->description('key_2に紐づく文字列')
                ->example('fuga'),
        );
}

キー: 値（integer）

下記のようなスキーマを定義したい。
```
{
  "key_3": 1
}
```

下記の様にスキーマクラスで定義する。

public function build(): SchemaContract
{
    return Schema::object('UserUpdateOkResponse')
        ->properties(
            Schema::integer('key_3')
                ->description('key_3に紐づく数値')
                ->example(1),
        );
}

キー: 値（boolean）

下記のようなスキーマを定義したい。
```
{
  "key_4": true
}
```

下記の様にスキーマクラスで定義する。

public function build(): SchemaContract
{
    return Schema::object('UserUpdateOkResponse')
        ->properties(
            Schema::boolean('key_4')
                ->description('key_4に紐づく真偽値')
                ->example(true),
        );
}

キー: 値（フォーマット指定）

下記のようなスキーマをフォーマットも含めて指定して定義したい。
```
{
  "date_info": "2022-05-13 19:20:43"
}
```

下記の様にスキーマクラスで定義する。

public function build(): SchemaContract
{
    return Schema::object('UserUpdateOkResponse')
        ->properties(
            Schema::string('date_info')
                ->description('日にち情報')
                ->format('date-time')
                ->example('2022-05-13 19:20:43'),
        );
}

用意されているフォーマット
- int32
- int64
- float
- double
- byte
- binary
- date
- date-time
- password
- uuid
ちなみに用意されていないフォーマットでも文字列で指定可能

例えば郵便番号の文字列にて「ハイフン無し」などのフォーマットを記載したい場合下記の様に書くことができる。

public function build(): SchemaContract
{
    return Schema::object('UserUpdateOkResponse')
        ->properties(
            Schema::string('zip')
                ->description('郵便番号')
                ->format('ハイフン無し')
                ->example('1234567'),
        );
}

nullableなキーの表現

下記のようなスキーマをnullableで定義したい（key_6に紐づく値がnullable）。
```
{
  "key_6": 123
}
```

下記の様にスキーマクラスで定義する。

public function build(): SchemaContract
{
    return Schema::object('UserUpdateOkResponse')
        ->properties(
            Schema::integer('key_6')
                ->nullable()
                ->example(123),
        );
}

requiredなキーの表現

下記のようなスキーマをrequiredで定義したい（key_7に紐づく値がrequired）。
```
{
  "key_7": 456
}
```

下記の様にスキーマクラスで定義する。

public function build(): SchemaContract
{
    return Schema::object('UserUpdateOkResponse')
        ->properties(
            Schema::integer('key_7')
                ->example(456),
        )
        ->required(
            'key_7',
        );
}

オブジェクトの中にオブジェクト

下記のようなスキーマをフォーマットを指定して定義したい。
```
{
  "user": {
    "id": 1,
    "name": "hoge hoge"
  }
}
```

下記の様にスキーマクラスで定義する。

public function build(): SchemaContract
{
    return Schema::object('UserUpdateOkResponse')
        ->properties(
            Schema::object('user')
                ->properties(
                    Schema::integer('id')
                        ->description('ID')
                        ->example(1),
                    Schema::string('name')
                        ->description('名前')
                        ->example('hoge hoge'),
                )
        );
}

オブジェクトの中の配列のの中にオブジェクト

下記のようなスキーマをフォーマットを指定して定義したい。

{
  "users": [
    {
      "id": 1,
      "name": "hoge hoge"
    }
  ]
}

下記の様にスキーマクラスで定義する　。

public function build(): SchemaContract
{
    return Schema::object('UserUpdateOkResponse')
        ->properties(
            Schema::array('users')
                ->items(
                    Schema::object()
                        ->properties(
                            Schema::integer('id')
                                ->description('ユーザーID')
                                ->example(1),
                            Schema::string('name')
                                ->description('ユーザー名')
                                ->example('hoge hoge'),
                        )
                )
        );
}