laravel-openapiライブラリ ドキュメントを出力してみる 番外編 スキーマの構造

# 概要

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

# 書き方

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

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

    ```json
    {
      "key_1": "hoge"
    }
    ```

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

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

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

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

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

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

    ```php
    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）

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

    ```json
    {
      "key_3": 1
    }
    ```

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

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

### キー: 値（boolean）

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

    ```json
    {
      "key_4": true
    }
    ```

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

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

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

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

    ```json
    {
      "date_info": "2022-05-13 19:20:43"
    }
    ```

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

    ```php
    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
- ちなみに用意されていないフォーマットでも文字列で指定可能
- 例えば郵便番号の文字列にて「ハイフン無し」などのフォーマットを記載したい場合下記の様に書くことができる。

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

### nullableなキーの表現

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

    ```json
    {
      "key_6": 123
    }
    ```

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

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

### requiredなキーの表現

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

    ```json
    {
      "key_7": 456
    }
    ```

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

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

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

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

    ```json
    {
      "user": {
        "id": 1,
        "name": "hoge hoge"
      }
    }
    ```

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

    ```php
    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'),
                    )
            );
    }
    ```

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

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

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

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

    ```php
    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'),
                            )
                    )
            );
    }
    ```