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

概要

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