A $ref property identifies another schema or reusable OpenAPI component by document location. Its value uses a JSON Pointer, such as #/components/schemas/Product, to reuse a definition instead of copying it. section 7.7.1 section 7.8
Reuse one Product schema
POST /products and GET /products/{productReference} can return the same resource model with schema: $ref: "#/components/schemas/Product". Updating Product in components.schemas changes both responses and prevents unwanted variations. section 7.7.1
Use $ref to centralize repeated API definitions:
- Reference reusable request bodies from components.requestBodies so create and update operations share one contract; place an operation-specific description beside the reference when needed. section 17.4
- Reference reusable responses from components.responses, including product-specific 404 responses built on a generic Error response. section 17.5.2
- Reference components in another OpenAPI file by combining a relative or absolute path or URL with the target JSON Pointer. section 17.6.2
- Use shared error schemas to constrain expected 500-error data and help prevent sensitive implementation details from leaking. section 12.10.5
Listing 7.12 References to reusable schemas
...
paths:
/products:
...
post:
...
responses:
"201":
...
content:
application/json:
schema:
$ref: "#/components/schemas/Product" #1
...
/products/{productReference}:
get:
...
responses:
"200":
...
content:
application/json:
schema:
$ref: "#/components/schemas/Product" #1
...
components:
schemas:
Product: ... #1
Inspect the Product response references and their shared components.schemas.Product target. section 7.7.1
