Required response field for nested objects

[xkrupa12]

Scribe version

4.38

PHP version

8.3

Framework

Laravel

Framework version

v11.27.2

Scribe config

------ SAME AS DEFAULT CONFIG ------

What happened?

First off cheers to @yannick-softwerft for delivering the feature itself. I happen to need it myself, but I had troubles marking response fields as required on nested objects in OpenAPI specs.

I have an endpoint that provides list of entities, response looks like this:

{
  "data": [
    {
      "name": "Wallet 1",
      "primary": true,
      "currency": "EUR",
      "available_balance": 99.5
    },
    {
      "name": "Wallet 2",
      "primary": false,
      "currency": "EUR",
      "available_balance": 0.0
    }
  ]
}

Here's the endpoint signature and relevant part of docs:

// GetWalletsController
#[ResponseField('data', 'array', 'Wallets', required: true)]
#[ResponseField('data.name', 'string', 'Wallet name', required: true)]
#[ResponseField('data.primary', 'bool', 'Is primary wallet for given currency', required: true)]
#[ResponseField('data.currency', 'string', 'Wallet currency', required: true, enum: ['USD', 'EUR', 'JPY', 'SGD'])]
#[ResponseField('data.available_balance', 'float', 'Available balance', required: true)]
public function __invoke(): JsonResponse|JsonResource
{}

Expected result should look like this:

responses:
  200:
    description: ''
    content:
      application/json:
        schema:
          type: object
          example:
            data:
              -
                name: 'Wallet name'
                primary: true
                currency: USD
                available_balance: 90.99
          properties:
            data:
              type: array
              example:
                -
                  name: 'Wallet name'
                  primary: true
                  currency: USD
                  available_balance: 90.99
              description: Wallets
              enum: []
              items:
                type: object
                properties:
                  name:
                    type: string
                    example: 'Wallet name'
                    description: 'Wallet name'
                    enum: []
                  primary:
                    type: boolean
                    example: true
                    description: 'Is primary wallet for given currency'
                    enum: []
                  currency:
                    type: string
                    example: USD
                    description: 'Wallet currency'
                    enum:
                      - USD
                      - EUR
                      - JPY
                      - SGD
                  available_balance:
                    type: number
                    example: 90.99
                    description: 'Available balance'
                    enum: []
              required:
                - name
                - primary
                - currency
                - available_balance
          required:
            - data

I was able to generate OpenAPI specs with required response fields list, but only for the single data object in it. For array of objects I wasn't able to achieve expected results. I also tried various notations to define the fields (omitting data itself, trying to hint in index as data.*.name, etc.), but to no avail.

After some digging through the code base I was able to fix the issue and am happy to create PR for it, assuming that my approach in describing the API was correct and this is indeed a bug/missing piece.

Docs

• I've checked the docs, the troubleshooting guide, and existing issues, but I didn't find a solution