How to correctly define additionalProperties with example in l5-swagger / Swagger-PHP?

Question

I am trying to document a Laravel API using l5-swagger (swagger-php). I have a request body where one property is a map of wallet IDs to effective dates, like this in PHP:

[
    11 => "2025-12-21",
    14 => "2025-11-29"
]

I want to define it in OpenAPI so that:

The property is an object with dynamic keys (wallet IDs).
Each value is a date string (Y-m-d).
The Swagger UI displays an example of the map.

What is the correct way to define an object with dynamic keys and date values in l5-swagger so that:

The PHP request can still be [id => date]

Swagger UI displays an example of the map

Doctrine annotations do not throw errors

Any help or working example would be greatly appreciated

Please clarify your specific problem or provide additional details to highlight exactly what you need. As it's currently written, it's hard to tell exactly what you're asking. — Community
– Community Bot, Commented Sep 28 at 6:14

IGP · Accepted Answer · 2025-10-07 18:20:01Z

You basically need to define an example. I think you can do it with Schemas too but I can't recall getting that to work.

I'm gonna assume your endpoint is POST /api/wallets for simplicity. You can use the RequestBody's description to explain the underlying key-value validation.

use OpenApi\Attributes as OAT;

class WalletController extends Controller
{
    #[OAT\Post(
        path: '/api/wallets',
        // other attributes like summary, description, security, tags...
        requestBody: new OAT\RequestBody(
            description: 'Object like "{<wallet_id>: <date_string>, ...}" where wallet id is a valid wallet id, and date string is in the format YYYY-MM-DD (or Y-m-d in PHP)',
            required: true,
            content: new OAT\JsonContent(
                examples: [
                    new OAT\Examples(
                        example: '4 Wallets',
                        summary: 'Associating wallets 11, 12, 13, 14',
                        value: [
                            11 => '2025-01-01',
                            12 => '2025-01-02',
                            13 => '2025-01-03',
                            14 => '2025-01-04',
                        ],
                    ),
                ],
            ),
        ),
    )]
    public function store(StoreWalletRequest $request)
    {
        // ...
    }

Collectives™ on Stack Overflow

How to correctly define additionalProperties with example in l5-swagger / Swagger-PHP?

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related