feat(api): Share OpenAPI schemas between InfluxDB 3 Core and Enterprise

[jstirnaman]

Problem

api-docs/influxdb3/core/v3/ref.yml (2,685 lines) and enterprise/v3/ref.yml (2,864 lines) are ~95% identical. Differences are:

• Product name substitutions ("Core" → "Enterprise")
• Documentation link paths
• 4 Enterprise-only endpoints: PatchConfigureTable, PatchConfigureDatabase, GetShowLicense, PostCreateResourceToken

This duplication creates maintenance burden and drift risk.

Proposed Solution

Use Redocly CLI overlays to maintain a single shared base with product-specific overrides.

api-docs/influxdb3/
├── shared/v3/base.yml          # Single source of truth (~2,600 lines)
├── core/v3/overlay.yml         # Product name only (~20 lines)
├── enterprise/v3/overlay.yml   # Product name + 4 paths (~100 lines)

Build command:

npx @redocly/cli bundle shared/v3/base.yml \
  --overlay=core/v3/overlay.yml \
  -o core/v3/ref.yml

Why Overlays (vs $ref)

• Declare what's different, not what's the same
• Adding paths to base automatically includes them everywhere
• Native Redocly CLI support
• Cleaner than 40+ explicit $ref lines with URL escaping

What Stays Unchanged

• .config.yml files
• content/ override mechanism (info.yml, servers.yml, tag-groups.yml)
• generate-openapi-articles.ts and link placeholder transformation
• postProcess decorators

Migration Steps

1. Copy Core spec → shared/v3/base.yml, genericize product references
2. Extract 4 Enterprise-only paths → enterprise/v3/overlay.yml
3. Create minimal core/v3/overlay.yml (info overrides only)
4. Update getswagger.sh with bundleWithOverlay function
5. Verify generated specs match current output

Testing

• Compare path counts and operationIds before/after
• Verify article generation produces identical output
• Manual smoke test: both API pages render, Enterprise-only paths appear only on Enterprise