- 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
- read assertions from _build artifacts instead of source specs\n- capture issue 6939 plan for follow-up steps\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Post-process-specs.ts now writes resolved specs (with info, servers, and
tag overlays applied) to api-docs/_build/ instead of back to source files.
Downstream consumers (Redoc HTML generation, static spec copy) read from
_build/. Source specs in api-docs/ are never mutated by the pipeline.
This makes the pipeline idempotent — running it twice produces identical
output — and keeps source spec diffs free of YAML re-serialization noise.
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.
The clean step was deleting committed content directories (e.g.,
enterprise_influxdb/v1/api/) when running in --static-only mode.
Static-only should only copy specs to static/openapi/, not touch
content directories.
- 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
Extends the tag post-processor into a unified spec post-processor that
also applies info.yml and servers.yml content overlays. This replaces
two Redocly decorators (set-info, set-servers) with a single TypeScript
script, moving toward removing the Redocly dependency.
- Rename apply-tag-config.ts → post-process-specs.ts
- Add info overlay support (merges fields from content/info.yml)
- Add servers overlay support (replaces spec.servers from content/servers.yml)
- Use same discovery convention as Redocly docs-content.cjs (API-specific
first, product-level fallback)
- Load spec once, apply all transforms, write once if modified
- Skip Redocly postProcess for management specs in getswagger.sh (prevents
unwanted $ref chain collapsing)
- Restore management@0 API entries in cloud-dedicated and clustered configs
- 13 tests, 41 assertions, all passing
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.
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
Jason Stirnaman