Urgent.News

What's breaking now, across thousands of outlets.

Tech

OpenAPI Components: Reuse vs Duplication

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…

Reuse OpenAPI components, like schemas or parameters, via the $ref mechanism when the same structure serves multiple purposes. This consolidates the definition into a single source of truth, preventing the proliferation of duplicate types in generated client code. Conversely, use inline duplication for one-off structures that are expected to vary independently.

The components object acts as a registry for reusable design elements, including schemas, parameters, request bodies, responses, headers, examples, security schemes, links, and callbacks. These components only become part of an operation when referenced via a JSON reference such as $ref: #/components/schemas/Customer. A reference is a pointer, not a copy, ensuring identical field sets, types, and constraints across all operations that utilize it.

This reuse mechanism scales across multiple files in a split project, allowing a relative path to navigate to a component in another document.

Duplicating inline structures across operations leads to drift over time, with each copy evolving separately. Reviewing such documents is challenging, as differences become buried within hundreds of lines of code. Code generation reveals the true cost: a referenced component results in a single model being reused, whereas an inlined component generates four identical types, cluttering SDKs and forcing consumers to manage conversions.

Lint rules can detect unused components and structural duplicates but cannot determine if two copies were intended to stay in sync.

In summary, reuse components for stable, shared concepts that evolve together, while retaining inline structures for one-off variations. Carefully consider the size of shared definitions to avoid creating a "god component" that becomes a regression hotspot when modified. Refactoring should be a no-op for consumers, with tools like lint passes and resolved-output comparisons confirming that generated types remain consistent.

By applying these principles, shared components become a clarity-enhancing tool rather than a source of coupling within OpenAPI specifications.

Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.

Read the original at dev.to →

More in Tech

Every Rule We Added Had a Bug. So We Stopped Adding Rules.

We wrote a handful of small rules on November 12. Each one was a line or two. Each one was obviously right. A read-only review found a real bug in nearly every one of them before they shipped.

  • Every rule added to Since tool had a bug.
  • Rules were used for questions beyond code review scope.
  • Team stopped adding rules, relying on code analysis instead.

scrapy-playwright

scrapy-playwright 是 Scrapy 官方插件组织维护的下载处理器,用 Playwright for Python 驱动真实浏览器来抓取请求。它的定位是处理需要执行 JavaScript 的页面,同时保留 Scrapy 原有的调度和 item 处理流程。和前面聊的 curl_cffi 方案相比,它不是"模拟"浏览器指纹,而是直接用真浏览器,所以 TLS、HTTP/2、JS…

  • scrapy-playwright is official Scrapy plugin using Playwright for Python.
  • Enables handling JavaScript pages while preserving Scrapy flow.
  • Requires pip install scrapy-playwright playwright install chromium.

More from Monday 16 November →