- Add standard OpenAPI `externalDocs` field to all tags.yml files that
have `x-related` entries (uses first link as the primary doc link)
- Convert `externalDocs` to `{title, href}` objects in related links
instead of bare URL strings
- Strip `https://docs.influxdata.com` from description/summary fields
in `transformDocLinks()` so Hugo pages use relative paths
- Fix article generation reading from absolutified download spec instead
of the Hugo spec with relative links (new `hugoSpecPath` output)
- Add `externalDocs.url` support to `absolutifyLinks()` for downloads
Hugo-native templates for API
reference documentation. Operations render as server-side HTML instead
of client-side Redoc, providing faster page loads, full SEO
indexability, and consistent styling.
Architecture:
- Tag-based navigation: operations grouped by OpenAPI tag, accessed
via tag pages only (no individual operation URLs)
- Generation script auto-discovers products from .config.yml files,
deriving Hugo paths and menu keys from directory structure
- Per-tag JSON/YAML chunks for fast Hugo template rendering
- Inline curl examples generated from OpenAPI specs at build time
Templates (layouts/api/, layouts/partials/api/):
- tag-renderer.html: renders all operations for a tag
- operation.html: individual operation with parameters, request body,
responses, and schema rendering
- code-sample.html: curl examples with Ask AI integration
- section-children.html: tag listing on section index pages
- all-endpoints-list.html: all operations sorted by path
Generation (api-docs/scripts/generate-openapi-articles.ts):
- Auto-discovery from .config.yml replaces hardcoded productConfigs
- Each API section generates independently (no cross-spec merging)
- Frontmatter-driven template data (specDownloadPath, articleDataKey)
- Link transformation: /influxdb/version/ placeholders resolved to
product-specific paths
Removed:
- Redoc renderer, JavaScript components, and CSS
- Shadow DOM test infrastructure (~160 lines)
- Operation page generation (dead generatePathPages function)
- mergeArticleData() and slugifyDisplayName()
Styles (assets/styles/layouts/_api-*.scss):
- 3-column layout: sidebar, content, sticky TOC
- Theme-aware code blocks for curl examples
- Method badges (GET/POST/PUT/DELETE) with color coding
- Collapsible schema sections with depth tracking
Tests (cypress/e2e/content/api-reference.cy.js):
- Tag page rendering with operation structure
- Download button verification per section
- All-endpoints page with operation cards
- Related links from x-related OpenAPI extension
- Code sample and Ask AI link validation
- Split generic "v2 Compatibility" tag into "Buckets (v2 compatible)"
and "Delete (v2 compatible)" in both v1 specs and tags.yml
- Rewrite Authentication tag descriptions: explain that auth is
disabled by default, move explanation before security definitions
- Fix broken markdown link in auth descriptions ([enabled in the
configuration] had no URL)
- Fix x-related format in both v1 tags.yml (flat object → list)
- Fix Enterprise v1 x-related href to correct page path
- Fix Cloud Dedicated info.yml indentation (broke YAML parsing)
- Remove dual tags from v2-compat operations in both v1 specs,
add x-compatibility-version: v2 for Hugo-native badge rendering
- Fix Enterprise v1 spec version 1.11.6 → 1.12.2 (spec, examples)
- Add GET /shard-status endpoint to Enterprise v1 spec (was only
in the legacy content page)
- Document one-tag-per-operation convention in api-docs/README.md
- Update api-docs.instructions.md for current file layout and pipeline
- Add analyze-api-source agent for cross-product API docs analysis
Add ReDoc-Inject: <security-definitions> directive and scheme links to
the Authentication tag description in all 9 tags.yml files. This renders
the security scheme definitions inline in the Redoc HTML, matching the
pre-uplift behavior. Each product lists its actual security schemes with
anchor links to the scheme definitions section.
Add x-traitTag to TagConfig interface so the post-processor propagates
it from tags.yml into specs. Mark all supplementary documentation tags
(Authentication, Quick start, Headers, Usage, etc.) with x-traitTag: true
so Redoc renders them as documentation sections with descriptions rather
than empty operation groups. Also exclude root .config.yml from the
Redoc HTML generation find command.
- Flatten Core/Enterprise v3/ subdirectories to product root
- Rewrite generate-api-docs.sh as clean 3-step pipeline:
post-process-specs → Redoc HTML → static spec downloads
- Add --static-only flag to generate-openapi-articles.ts
- Remove circular getswagger.sh call from generate-openapi-articles.ts
- Remove dead execCommand function and --skip-fetch flag
- Apply post-processed tag enrichments to all spec files
Flatten Cloud v2 and OSS v2 spec directories to product root with
self-documenting filenames, matching the pattern used for influxdb3 products.
Remove all 5 v1-compatibility directories — those endpoints are already
included in the main spec (tagged as v1/v2 Compatibility).
Old v1-compat URLs are preserved as Hugo aliases for redirects.
Also includes:
- Migrate inline markdown links from management API spec descriptions
into tags.yml x-related fields (Cloud Dedicated + Clustered)
- Wire post-process-specs.ts into generate-api-docs.sh build pipeline
- Fix doubled static/openapi download filenames
- Update project plan with design decisions
Drop redundant version subdirectories and use self-documenting
filenames for 5 products:
v2-compat influxdb3:
cloud-dedicated/v2/ref.yml → cloud-dedicated/influxdb3-cloud-dedicated-openapi.yaml
cloud-serverless/v2/ref.yml → cloud-serverless/influxdb3-cloud-serverless-openapi.yaml
clustered/v2/ref.yml → clustered/influxdb3-clustered-openapi.yaml
v1:
influxdb/v1/v1/ref.yml → influxdb/v1/influxdb-oss-v1-openapi.yaml
enterprise_influxdb/v1/v1/ref.yml → enterprise_influxdb/v1/influxdb-enterprise-v1-openapi.yaml
Update .config.yml, getswagger.sh, and generate-openapi-articles.ts
to reference new paths.
Add apply-tag-config.ts that reads colocated tags.yml files and patches
OpenAPI spec tags in place (descriptions, x-related links, renames).
Runs between getswagger.sh and generate-openapi-articles.ts in the
build pipeline.
Create tags.yml for all 11 product specs:
- Core, Enterprise: extracted from existing spec tag metadata
- v2-compat, v2, v1: new descriptions and x-related links
Include test suite (16 assertions) covering description setting, tag
rename propagation, x-related links, stale/uncovered tag warnings,
silent skip when no config, and malformed YAML failure.
Remove the x-tagGroups vendor extension from 8 remaining OpenAPI spec
files. This Redocly extension was used for navigation grouping in the
old RapiDoc layout but is ignored by the Hugo-native API templates,
which generate pages from operation tags[] arrays.
Extract all api-docs/ changes from feat-api-uplift into a standalone
branch for independent testing and merging to master.
Changes include:
- Updated generation scripts (generate-openapi-articles.ts,
openapi-paths-to-hugo-data/index.ts) for Hugo-native templates
- Removed dead x-tagGroups infrastructure (decorator, config files)
- Updated Core and Enterprise specs with tag descriptions, x-related
links, and Cache Data tag split
- Added v1 product configs and specs (OSS v1, Enterprise v1)
- Updated getswagger.sh for renamed spec files
- Updated generate-api-docs.sh with clean regeneration support
- Adds missing examples for v1-compatible /query
- Fixes curl params in examples
- Removes unsupported async option from examples
- Updates terms for consistency with branding and influxdb3 docs
- Copies the missing POST /query operation from swaggerv1compat to the v2 ref.yml
- Effectively removes the separate v1-compat spec, and adds redirects and tags for v1-compat endpoints in v2/ref.yml
- Updates affected links
- OSS v2 supports partial writes and returns a 422 that describes rejected points, depending on the problem.
- Update API spec
- Move file to content/shared for Cloud
- Fix broken links reported by the e2e link checker.
- Add an e2e test for checking internal and external links in API reference docs. Low effort, big win.
- Add a custom x-influxdata-short-description field that replaces the previous non-standard summary field used by Redocly.
- Double quote the title and description vars to preserve the entire value when passing them to the CLI
- Adds InfluxDB 3 Core API reference
- Updates scripts
- Removes non-valid info.summary field from specs, replaces with description in metadata
- Simplifies frontmatter generation for HTML template
- Reorg of file structure to mirror the content structure.
- Moves OSS v2 into v2/v2/ref.yml to follow the same pattern as others
- Replaces isDefault API config field with specific aliases.
- Misc. fixes.
- Remove generated HTML files.
Jason Stirnaman
Jason Stirnaman