OpenAPI 3.1 YAMLの書き方

とにかく分からないので１行ずつ意味を理解していく。

「OpenAPI Specification v3.1.0」を読みながら書いています。

抜けている定義行があるかもしれません。
また、Swagger UIで随時previewしていますが細かい誤りある可能性があります。

## 分類方法
初見だとOpenAPIの規定値と規定値外で混乱するため以下の３種類に分類
- ***「必須」*** (Required)：OpenAPI3.1の予約語。必ず書かなければならない定義
（ただし、上位インデントが「任意」の場合は記載が不要になることがある）
- ***「任意」***(Optional)：OpenAPI3.1の予約語。省略可能な定義
- ***「独自定義」*** (Custom-defined)：OpenAPI3.1 YAMLに関係ない任意名の定義

## YAML
```yaml:ルートレベルの例：openapi【string】
openapi: 3.1.0 # 必須: OpenAPIのバージョン【string】
```

```yaml:ルートレベルの例：info【Info Object】
info:  # 必須: APIに関する基本情報【Info Object】
  ### 【Info Object】 ###
  title: API名  # 必須: APIのタイトル【string】
  description: 説明  # 任意: APIの説明【string】
  termsOfService: https://example.com/terms/  # 任意: APIの利用規約のURL【string】
  contact:  # 任意: APIに関する連絡先【Contact Object】
    name: 連絡先名  # 任意: 連絡先の名前【string】
    url: https://example.com/contact/  # 任意: 連絡先のURL【string】
    email: aa@aa.ne.jp  # 任意: 連絡先のメールアドレス【string】
  license:  # 任意: APIのライセンス情報【License Object】
    name: ライセンス名  # 必須: ライセンスの名前【string】
    identifier: ライセンス識別子  # 任意: ライセンスの識別子【string】
    url: https://example.com/license/  # 任意: ライセンスのURL【string】
  version: 1.0.0  # 必須: APIのバージョン【string】
```

```yaml:ルートレベルの例：jsonSchemaDialect【string】
jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema"  # 任意: 使用するJSON Schemaのバージョン【string】
```

```yaml:ルートレベルの例：servers【[Server Object]】
servers:  # 必須: APIがホストされるサーバーの情報【[Server Object]】
  ### 【Server Object】 ###
  - url: /api/{version}  # 必須: サーバーのURL【string】
    description: 説明  # 任意: URLの説明【string】
    variables:  # 任意: URLの変数を定義（変数定義時に使用）【Map[string, Server Variable Object]】
      ### string(MapのKey)
      version:  # 独自定義: バージョン変数【string】
        ### Server Variable Object(MapのValue) ###
        default: v1  # 必須: 変数のデフォルト値【string】
        description: 変数の説明  # 任意: 変数の説明【string】
```

```yaml:ルートレベルの例：paths【Paths Object】
paths:  # 必須: 各エンドポイントのパスとその操作を定義【Paths Object】
  ### 【Paths Object】 ###
  /test/info:  # 独自定義: エンドポイント名【Path Item Object】
    ### 【Path Item Object】 ###
    # $ref: # 任意【string】（割愛）
    summary: 概要  # 任意: エンドポイントの概要【string】
    description: 説明  # 任意: エンドポイントの詳細な説明【string】
    post:  # 必須: HTTPメソッド（get, put, post, delete, options, head, patch, trace, servers）【Operation Object】
      ### 【Operation Object】 ###
      # tags: # 任意【[string]】（割愛）
      summary: 概要  # 任意: エンドポイントの概要【string】
      description: 説明  # 任意: エンドポイントの説明【string】
      # externalDocs: # 任意【External Documentation Object】（割愛） 
      # operationId: # 任意【string】（割愛）
      parameters:  # 任意: エンドポイントのリクエストパラメータ【[Parameter Object | Reference Object]】
        ### 【Parameter Object】 ###
        - name: testId2  # 必須: パラメータの名前【string】
          in: query  # 必須: パラメータの場所（query, header, path, cookie）【string】
          description: パラメータの説明  # 任意: パラメータの説明【string】
          required: true  # 必須 or 任意（inがpathの場合は必須かつtrue、query, header, cookiesの場合は任意【boolean（default値はfalse扱い）】
          ### deprecated: # 任意【boolean】（割愛）
          ### allowEmptyValue: # 任意【boolean】（割愛）
          style: form  # 任意: パラメータのスタイル（matrix, label, form, simple, spaceDelimited, pipeDelimited, deepObject）【string（default値はinの値に応じて変わる）】
          # explode: # 任意【boolean（default値はinの値に応じて変わる）】（割愛）
          # allowReserved: # 任意【boolean（default値はfalse扱い）】（割愛）
          schema:  # 任意: パラメータのスキーマ【Schema Object】
            ### 【Schema Object】 ###
            ### json-schema.orgを参照して記述する ###
            ## https://json-schema.org/draft/2020-12/vocab/core
            ## ⇒ JSON Schemaの基本的な構造やメタデータに関する定義が記載されている。
            ## https://json-schema.org/draft/2020-12/vocab/validation
            ## ⇒ JSON Schemaのバリデーションルールが定義されている。データ型（type）、制約（minimum, maximum, patternなど）、必須プロパティ（required）など、スキーマのバリデーションに関する詳細な情報も記載。
            type: string  # 必須: パラメータのタイプ【string】
            format: uuid  # 任意: パラメータのフォーマット【string】
            minLength: 36  # 任意: パラメータの最小長【integer】
            maxLength: 36  # 任意: パラメータの最大長【integer】
            pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'  # 任意: パラメータの正規表現パターン【string】
            description: UUID形式のパラメータ  # 任意: パラメータの詳細な説明【string】
            example: '123e4567-e89b-12d3-a456-426614174000'  # 任意: パラメータの例【Any】
        - $ref: '#/components/parameters/testId'  # 任意: パラメータの参照【Reference Object】
      requestBody:  # 任意: リクエストボディの定義【Request Body Object | Reference Object】
        ### 【Request Body Object】 ###
        description: 説明  # 任意: リクエストボディの説明【Request Body Object】【string】
        required: true  # 任意: リクエストボディが必須かどうか【boolean（default値はfalse扱い）】
        content:  # 必須: リクエストボディのコンテンツタイプとスキーマ【Map[string, Media Type Object]】
          ### string(MapのKey) ###
          application/json:  # 必須: コンテンツタイプ【string】
            ### 【Media Type Object(MapのValue)】 ###
            schema:  # 任意: スキーマの参照【Schema Object】
              ### 【Schema Object】 ###
              ### json-schema.orgを参照して記述する ###
              ## https://json-schema.org/draft/2020-12/vocab/core
              ## ⇒ JSON Schemaの基本的な構造やメタデータに関する定義が記載されている。
              ## https://json-schema.org/draft/2020-12/vocab/validation
              ## ⇒ JSON Schemaのバリデーションルールが定義されている。データ型（type）、制約（minimum, maximum, patternなど）、必須プロパティ（required）など、スキーマのバリデーションに関する詳細な情報も記載。
              $ref: '#/components/schemas/CustomerInfoRequestBody'  # 必須: スキーマの参照【Reference Object】
            example:  # 任意: リクエストボディのサンプルデータ【any】
              customerId: 'ほげほげ'  # 任意：サンプルデータの顧客ID【string】
            # examples:  # 任意【Map[string, Example Object]】（割愛）
            # encoding: 任意【Map[string, Encoding Object]】（割愛）
        # $ref: # 任意【Refaerence Object】（割愛）
      responses:  # 必須: レスポンスの定義【Map[string, Response Object | Reference Object]】
        ### string(MapのKey) ###
        '200':  # 独自定義: HTTPステータスコード（一つ以上必須）【string】
          ### 【Response Object(MapのValue)】 ###
          description: 情報の取得に成功しました  # 必須: レスポンスの説明【string】
          # headers: # 任意【Map[string, Header Object | Reference Object]】（割愛）
          content:  # 必須: レスポンスのコンテンツタイプとスキーマ【Map[string, Media Type Object]】
            ### string(MapのKey) ###
            application/json:  # 必須: コンテンツタイプ【string】
              ### 【Media Type Object(MapのValue)】 ###
              schema:  # 必須: スキーマの参照【Schema Object】
                ### 【Schema Object】 ###
                ### json-schema.orgを参照して記述する ###
                ## https://json-schema.org/draft/2020-12/vocab/core
                ## ⇒ JSON Schemaの基本的な構造やメタデータに関する定義が記載されている。
                ## https://json-schema.org/draft/2020-12/vocab/validation
                ## ⇒ JSON Schemaのバリデーションルールが定義されている。データ型（type）、制約（minimum, maximum, patternなど）、必須プロパティ（required）など、スキーマのバリデーションに関する詳細な情報も記載。
                $ref: '#/components/schemas/TestAccountInfoResponse'  # 必須: スキーマの参照パス【Reference Object】
              example:  # 任意: レスポンスのサンプルデータ【any】
                message: '操作が成功しました'  # 任意：サンプルデータのメッセージ【string】
              # examples:  # 任意【Map[string, Example Object]】（割愛）
              # encoding: 任意【Map[string, Encoding Object]】（割愛）
        ### string(MapのKey) ###
        '400':  # 独自定義: ステータスコード（一つ以上必須）【string】
          ### 【Reference Object(MapのValue)】 ###
          $ref: '#/components/responses/badRequest'  # 必須: レスポンスの参照（参照記述）【Reference Object】
        ### string(MapのKey) ###
        default:  # 任意: デフォルトレスポンス【string】
          ### 【Response Object(MapのValue)】 ###
          description: エラーレスポンス  # 必須: レスポンスの説明【string】
          # headers: # 任意【Map[string, Header Object | Reference Object]】（割愛）
          content:  # 必須: レスポンスのコンテンツタイプとスキーマ【Map[string, Media Type Object]】
            ### string(MapのKey) ###
            application/json:  # 必須: コンテンツタイプ【string】
              ### 【Media Type Object(MapのValue)】 ###
              schema:  # 必須: スキーマの参照【Schema Object】
                ### 【Schema Object】 ###
                ### json-schema.orgを参照して記述する ###
                ## https://json-schema.org/draft/2020-12/vocab/core
                ## ⇒ JSON Schemaの基本的な構造やメタデータに関する定義が記載されている。
                ## https://json-schema.org/draft/2020-12/vocab/validation
                ## ⇒ JSON Schemaのバリデーションルールが定義されている。データ型（type）、制約（minimum, maximum, patternなど）、必須プロパティ（required）など、スキーマのバリデーションに関する詳細な情報も記載。
                type: object  # 必須: オブジェクト型のスキーマ【string】
                properties:  # 必須: オブジェクトのプロパティ【Map[string, Schema Object]】
                  error:  # 必須: プロパティの名前【string】
                    type: string  # 必須: プロパティのタイプ【string】
                    description: エラーメッセージ  # 任意: プロパティの説明【string】
                    example: 'ERRORが発生しました'  # 任意: プロパティの例【any】
              example: 'エラーが発生しました'  # 任意: プロパティの例【any】
              # examples:  # 任意【Map[string, Example Object]】（割愛）
              # encoding: 任意【Map[string, Encoding Object]】（割愛）
      # callbacks:  # 任意【Map[string, Callback Object | Reference Object]】（割愛）
      # deprecated:  # 任意【boolean】（割愛）
      security:  # 任意: エンドポイントのセキュリティ設定【[Security Requirement Object]】
        ### 【Security Requirement Object】 ###
        - bearerAuth: []  # 独自定義: セキュリティスキームの参照【string】
      # servers:  # 任意【[Server Object]】（割愛）
```

```yaml:ルートレベルの例：components【Components Object】
components:  # 任意: 再利用可能なスキーマ、レスポンス、パラメータ、リクエストボディ、セキュリティスキームなどを定義【Components Object】
  schemas:  # 任意: 再利用可能なスキーマの定義【Map[string, Schema Object]】
    ### string(MapのKey) ###
    CustomerInfoRequestBody:  # 独自定義: 顧客情報リクエストのスキーマ【string】
      ### 【Schema Object(MapのValue)】 ###
      ### json-schema.orgを参照して記述する ###
      ## https://json-schema.org/draft/2020-12/vocab/core
      ## ⇒ JSON Schemaの基本的な構造やメタデータに関する定義が記載されている。
      ## https://json-schema.org/draft/2020-12/vocab/validation
      ## ⇒ JSON Schemaのバリデーションルールが定義されている。データ型（type）、制約（minimum, maximum, patternなど）、必須プロパティ（required）など、スキーマのバリデーションに関する詳細な情報も記載。
      type: object  # 必須: スキーマのタイプ【string】
      properties:  # 必須: スキーマのプロパティ【object】
        customerId:  # 独自定義: プロパティ【object】
          type: string  # 必須: プロパティのタイプ【string】
          description: 説明  # 任意: プロパティの説明【string】
          example: 'hogehoge'  # 任意: プロパティの例【any】
    ### string(MapのKey) ###
    TestAccountInfoResponse:  # 独自定義: 銀行口座情報レスポンスのスキーマ【string】
      ### 【Schema Object(MapのValue)】 ###
      ### json-schema.orgを参照して記述する ###
      ## https://json-schema.org/draft/2020-12/vocab/core
      ## ⇒ JSON Schemaの基本的な構造やメタデータに関する定義が記載されている。
      ## https://json-schema.org/draft/2020-12/vocab/validation
      ## ⇒ JSON Schemaのバリデーションルールが定義されている。データ型（type）、制約（minimum, maximum, patternなど）、必須プロパティ（required）など、スキーマのバリデーションに関する詳細な情報も記載。
      type: object  # 必須: スキーマのタイプ【string】
      properties:  # 必須: スキーマのプロパティ【object】
        testName:  # 独自定義: プロパティ【object】
          type: string  # 必須: プロパティのタイプ【string】
          description: 名前  # 任意: プロパティの説明【string】
        accountNumber:  # 独自定義: プロパティ【object】
          type: string  # 必須: プロパティのタイプ【string】
          description: 説明  # 任意: プロパティの説明【string】
  responses:  # 任意: 再利用可能なレスポンスの定義（components配下は予約語のresponsesの使用が推奨される）【Map[string, Response Object | Reference Object]】
    ### string(MapのKey) ###
    badRequest:  # 独自定義: 不正なリクエストのレスポンス【string】
      ### 【Response Object(MapのValue)】 ###
      description: 不正なリクエスト  # 必須: レスポンスの説明【string】
      # headers: # 任意【Map[string, Header Object | Reference Object]】（割愛）
      content:  # 必須: レスポンスのコンテンツタイプとスキーマ【object】
        ### string(MapのKey) ###
        application/json:  # 必須: コンテンツタイプ【object】
          ### 【Media Type Object(MapのValue)】 ###
          schema:  # 必須: スキーマの定義【object】
            ### 【Schema Object】 ###
            ### json-schema.orgを参照して記述する ###
            ## https://json-schema.org/draft/2020-12/vocab/core
            ## ⇒ JSON Schemaの基本的な構造やメタデータに関する定義が記載されている。
            ## https://json-schema.org/draft/2020-12/vocab/validation
            ## ⇒ JSON Schemaのバリデーションルールが定義されている。データ型（type）、制約（minimum, maximum, patternなど）、必須プロパティ（required）など、スキーマのバリデーションに関する詳細な情報も記載。
            type: object  # 必須: スキーマのタイプ【string】
            properties:  # 必須: スキーマのプロパティ【object】
              message:  # 任意: エラーメッセージのプロパティ【object】
                type: string  # 必須: プロパティのタイプ【string】
                description: エラーメッセージ  # 任意: プロパティの説明【string】
  parameters:  # 任意: 再利用可能なパラメータの定義（components配下は予約語のparametersの使用が推奨される）【Map[string, Parameter Object | Reference Object]】
    ### string(MapのKey) ###
    testId:  # 独自定義: 再利用可能なパラメータの名前【string】
      ### 【Parameter Object(MapのValue)】 ###
      name: testId  # 必須: パラメータの名前（直接記述）【string】
      in: query # 必須: パラメータの場所（例: query, header, path, cookie）【string】
      required: true  # 必須: パラメータが必須かどうか【boolean】
      ### deprecated: # 任意【boolean】（割愛）
      ### allowEmptyValue: # 任意【boolean】（割愛）
      style: form  # 任意: パラメータのスタイル（matrix, label, form, simple, spaceDelimited, pipeDelimited, deepObject）【string（default値はinの値に応じて変わる）】
      # explode: # 任意【boolean（default値はinの値に応じて変わる）】（割愛）
      # allowReserved: # 任意【boolean（default値はfalse扱い）】（割愛）
      schema:  # 必須: パラメータのスキーマ【Schema Object】
        ### 【Schema Object】 ###
        ### json-schema.orgを参照して記述する ###
        ## https://json-schema.org/draft/2020-12/vocab/core
        ## ⇒ JSON Schemaの基本的な構造やメタデータに関する定義が記載されている。
        ## https://json-schema.org/draft/2020-12/vocab/validation
        ## ⇒ JSON Schemaのバリデーションルールが定義されている。データ型（type）、制約（minimum, maximum, patternなど）、必須プロパティ（required）など、スキーマのバリデーションに関する詳細な情報も記載。
        type: string  # 必須: パラメータのタイプ【string】
      description: パラメータの説明  # 任意: パラメータの説明【string】
  # examples:  # 任意【Map[string, Example Object]】（割愛）
  # requestBodies:  # 任意【Map[string, Request Body Object | Reference Object]】（割愛）
  # headers:  # 任意【Map[string, Header Object | Reference Object]】（割愛）
  # securitySchemes:  # 任意【Map[string, Security Scheme Object | Reference Object]】（割愛）
  # links:  # 任意【Map[string, Link Object | Reference Object]】（割愛）
  # callbacks:  # 任意【Map[string, Callback Object | Reference Object]】（割愛）
  # pathItems:  # 任意【Map[string, Path Item Object | Reference Object]】（割愛）
```

```yaml:ルートレベルの例：割愛
# security:  # 任意【Map[string, Security Requirement Object]】（割愛）
# tags:  # 任意【[Tag Object]】（割愛）
# externalDocs:  # 任意【External Documentation Object】（割愛）
```

## 記載内容の補足
#### 「-」
リストを表現
```yaml
servers:
  - url: /api/v1
    description: バージョン1のAPI
  - url: /api/v2
    description: バージョン2のAPI
```

#### 「リクエストボディの定義方法」
| HTTPメソッド | parameters | requestBody | responses |
|--------------|------------|-------------|-----------|
| GET          | 任意       | 指定不可    | 必須      |
| PUT          | 任意       | 任意        | 必須      |
| POST         | 任意       | 任意        | 必須      |
| DELETE       | 任意       | 指定不可    | 必須      |
| OPTIONS      | 任意       | 指定不可    | 必須      |
| HEAD         | 任意       | 指定不可    | 必須      |
| PATCH        | 任意       | 任意        | 必須      |
| TRACE         | 任意       | 指定不可    | 必須      |


#### 「`in`」
- `query`
URL のクエリ文字列部分に含まれるパラメータ。通常、? の後に続くキーと値のペアとして指定される。
使用例: https://example.com/api/resource?param1=value1&param2=value2
```yaml
parameters:
  - name: param1
    in: query
    required: true
    schema:
      type: string
    description: クエリパラメータの説明
```

- `header`
HTTP ヘッダーに含まれるパラメータ。リクエストやレスポンスのメタデータとして使用される。
使用例: Authorization: Bearer <token>
```yaml
parameters:
  - name: X-Custom-Header
    in: header
    required: false
    schema:
      type: string
    description: ヘッダーパラメータの説明
```

- `path`
URL パスの一部として指定されるパラメータ。リソースの識別子として使用される。
使用例: https://example.com/api/resource/{id}
```yaml
parameters:
  - name: id
    in: path
    required: true
    schema:
      type: string
    description: パスパラメータの説明
```

- `cookie`
HTTP クッキーに含まれるパラメータ。クライアントとサーバー間で状態を維持するために使用される。
使用例: Cookie: sessionId=abc123
```yaml
parameters:
  - name: sessionId
    in: cookie
    required: true
    schema:
      type: string
    description: クッキーパラメータの説明
```


|`in`の設定値 | 用途 | 使用例 |
|--------------|------------|-------------|
|`query`| リクエストの動作変更に使用|検索クエリ、ソート順、ページ番号など|
|`header`| リクエストのメタデータ提供に使用|認証トークン、カスタムヘッダー|
|`path`| リソースを一意に識別するのに使用|リソース ID、ユーザー名など|
|`cookie`| クライアントとサーバー間の状態維持に使用|セッション ID、トラッキング情報など|

| `in`の設定値 | required | style(デフォルト値)  | allowReserved |
|--------------|----------|----------------------|---------------|
| `query`      | 任意     | form                 | false         |
| `header`     | 任意     | simple               | -(使用不可)   |
| `path`       | 必須     | simple               | -(使用不可)   |
| `cookie`     | 任意     | form                 | -(使用不可)   |

| `in`の設定値 | styleの設定値       | explodeのデフォルト値 |
|------------------------|---------------------|-----------------------|
| `query`                | form                | true                  |
|                        | spaceDelimited      | false                 |
|                        | pipeDelimited       | false                 |
|                        | deepObject          | true                  |
| `header`               | simple              | false                 |
| `path`                 | simple              | false                 |
|                        | matrix              | false                 |
|                        | label               | false                 |
| `cookie`               | form                | true                  |