Menu

OpenAPI Components: Reuse vs Duplication
📰

OpenAPI Components: Reuse vs Duplication

DEV Community: api·Jeff·2 days ago
#tjLnhuZW
#devtoapi#devto#dev#components#component
Reading 0:00
15s threshold

Quick answer: Reuse an OpenAPI component with $ref whenever the same schema, parameter, or response is genuinely one concept used in multiple places; it gives you a single source of truth and keeps generated clients from sprouting duplicate types. Inline duplication is the right call for one-off structures or fields that look alike but are expected to change independently.

What components and $ref actually do

The components object is a registry of reusable design elements: schemas, parameters, request bodies, responses, headers, examples, security schemes, links, and callbacks. Nothing in components is exposed on its own; it becomes part of an operation only when something points at it with a JSON reference such as $ref: '#/components/schemas/Customer' .

A reference is a pointer, not a copy. Every operation that points to Customer resolves to the same definition, so the field set, types, and constraints stay identical by construction.…

Continue reading — create a free account

Join HashtagPLUS to read full articles, follow hashtags, vote, and join the conversation.