ContextQMD
Back to Swagger Php

References

docs/guide/references.md

6.1.21.5 KB
Original Source

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

<codeblock id="using-references"> <template v-slot:at>
php
#[OA\Schema(
  schema: 'product_id',
  type: 'integer',
  format: 'int64',
  description: 'The unique identifier of a product in our catalog',
)]
</template> <template v-slot:an>
php
/**
 * @OA\Schema(
 *   schema="product_id",
 *   type="integer",
 *   format="int64",
 *   description="The unique identifier of a product in our catalog"
 * )
 */
</template> </codeblock>

Results in:

yaml
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

<codeblock id="refer-to-$ref"> <template v-slot:at>
php
    #[OA\Property(ref: "#/components/schemas/product_id")]
    public $id;
</template> <template v-slot:an>
php
    /**
     * @OA\Property(ref="#/components/schemas/product_id")
     */
    public $id;
</template> </codeblock>

::: info Examples There are more use cases on how to use refs in the using-refs example. :::