Swagger OpenAPI use object with schema instead of array

Question

I'm using L5 Swagger from DarkOnLine to generate Swagger docs using OpenApi schematics.

To use schema I can do

@OA\Property(property="certification", type="array", @OA\Items(ref="#/components/schemas/Certification"))

and it works perfectly fine and shows as

"certification": [
    {
      "certification_id": 0,
      "name": "string"
    }
  ],

. But it creates an array block with square brackets with multiple objects inside it.

How do I use the same working but lose the array. Something like

@OA\Property(property="certification", type="object", @OA\Items(ref="#/components/schemas/Certification")),

so as to remove square brackets and show only object like.

"certification": {
      "certification_id": 0,
      "name": "string"
 }

Woke

Answer 1

You can do:

@OA\Property(
  property="certification", 
  ref="#/components/schemas/Certification"
)

The @OA\Items annotation is only used when you want to specify what are the properties inside an array (see Data Types: array).

In your case you just want to describe an object so you just have to reference the object's schema in the property and remove @OA\Items.

Waggle

Answer 2

You can define sub-properties like this:

@OA\Schema(
   schema="MySchema",
   type="object",
   @OA\Property(property="MyObject",type="object",
      @OA\Property(property="sub_prop1",type="string",example="active"),
      @OA\Property(property="value",type="integer",example="3"),
   ),
)

or by using

@OA\Schema(
   schema="MySchema",
   type="object",
   $ref: '#/components/schemas/MyObject'
)

Sampler