References

It's quite common that endpoints have some overlap in either their request or response data. To keep things DRY (Don't Repeat Yourself) the specification allows reusing components using $ref's

#[OA\Schema(
  schema: 'product_id',
  type: 'integer',
  format: 'int64',
  description: 'The unique identifier of a product in our catalog',
)]

/**
 * @OA\Schema(
 *   schema="product_id",
 *   type="integer",
 *   format="int64",
 *   description="The unique identifier of a product in our catalog"
 * )
 */

Results in:

openapi: 3.0.0
components:
  schemas:
    product_id:
      description: "The unique identifier of a product in our catalog"
      type: integer
      format: int64

This doesn't do anything by itself, but now you can reference this fragment by its path in the document tree #/components/schemas/product_id

    #[OA\Property(ref: "#/components/schemas/product_id")]
    public $id;

    /**
     * @OA\Property(ref="#/components/schemas/product_id")
     */
    public $id;

Examples

There are more uses cases on how to use refs in the using-refs example.