- Move Hugo spec (relative links) to _build/ instead of static/ with
-hugo- suffix, preserving original basenames for tag spec filenames
- Add articleDataKey, articleSection, and specDownloadPath to generated
section and tag page frontmatter for sidebar nav and download button
- Fix sidebar link test to use #nav-tree instead of .sidebar (avoids
matching the hamburger toggle link)
Extract fetchAndProcess and fetchManagementSpec helpers to deduplicate
nine near-identical update functions. Cache granite clone across calls
to avoid redundant fetches. Replace if/elif dispatch with case, fix
quoting, remove dead code (versionDirs, npx --version), update help
text, and use subshells for cd safety.
Passes shellcheck with zero warnings.
- 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
The regex that stripped Redoc anchor links didn't account for nested
parentheses in tag names like Authorizations-(API-tokens)), leaving
orphaned closing parens in descriptions and tag references.
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
The original v3 specs had multi-paragraph descriptions for trait tags
(Quick start, Headers and parameters, Migrate) and operation tags
(Cache, Processing engine, Write data) with tables, code blocks,
and structured content. The tags.yml files replaced these with
one-liner summaries, which post-process-specs.ts then applied over
the rich spec descriptions.
Restore all descriptions to match the original spec content.
- 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.
- 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.
The find command in generate-api-docs.sh matched the Redocly root
config (api-docs/.config.yml) which has no apis key, causing yq to
fail with "cannot get keys of \!\!null".
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
Strip title, version, description, license, and contact from Core and
Enterprise info.yml overlays so the values from docs-tooling generated
specs are preserved. Keep only x-influxdata-* fields used for Hugo
page metadata.
Fix set-info.cjs decorator to not blank version or summary when the
overlay omits them — the old else branches would clear spec values
that should pass through.
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
Rename Core and Enterprise OpenAPI spec files from ref.yml to
descriptive names (influxdb3-core-openapi.yaml, influxdb3-enterprise-openapi.yaml).
Copy specs to static/openapi/ and add download links in the API description.
* fix(influxdb3): update to v3.8.2, add --tls-no-verify and release notes
- Update latest_patch to 3.8.2 for Core and Enterprise in products.yml
(3.8.1 was internal-only)
- Add --tls-no-verify and INFLUXDB3_TLS_NO_VERIFY env var to all
remaining CLI pages (query, write, show, enable, disable, update,
test, stop, create/delete cache and file_index commands)
- Add safety disclaimer: "Not recommended in production" per review
- Standardize --tls-ca description across all CLI pages
- Add v3.8.2 release notes for Core and Enterprise
Addresses review feedback from hiltontj and jstirnaman on PR #6774.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* chore(influxdb3): remove PachaTree references from documentation
Remove all PachaTree-related content that is not yet ready for
public documentation:
- Remove --use-pacha-tree from Enterprise serve CLI reference
- Replace influxdb3_pacha_tree log filter example with influxdb3_enterprise
- Remove influxdb3_pacha_tree from component names table
- Remove PachaTree storage engine entry from v3.7.0 release notes
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Update content/shared/v3-core-enterprise-release-notes/_index.md
* Apply suggestions from code review
---------
Co-authored-by: peterbarnett03 <peter.barnett03@gmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
* fix(influxdb3): Mark disabled field as required in processing engine trigger API specs
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
* Add HTTP API examples to Processing Engine plugin documentation (#6789)
- Add disabled field and api-ref to API examples per review feedback
- Add api-ref to upload plugin endpoint and remove duplicate link sentence
- Convert {{% code-placeholders %}} shortcode to placeholders code block
attribute for cleaner syntax
- Add second argument to token-link shortcodes for admin tokens to
ensure consistent linking to /admin/tokens/admin/ path
- Follows PR 6789 review feedback for processing engine documentation
fix(influxdb3): update placeholder and token-link syntax in get-started
- Convert code-placeholders wrapper shortcodes to code block attributes
* fix(influxdb3): Fix broken trigger anchor links in plugin documentation
Rename "Set up a trigger" heading to "Create a trigger" and update
all internal anchor references to match.
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
Co-authored-by: Jason Stirnaman <jstirnaman@influxdata.com>
- Updates identify-version guide and Core/Ent3 API specs
- Use GET. HEAD `/ping` responds with `404`
- Specify default auth requirement for Enterprise
- Tested with Core and Ent v3.8.0
Add the show_deleted query parameter to the list databases endpoint
in the Enterprise API spec. This parameter allows users to include
soft-deleted databases in the response.
closes#6610
- Add DELETE /api/v3/configure/database/retention_period
- Add DELETE /api/v3/configure/token
- Add POST /api/v3/configure/token/named_admin
- Add PUT /api/v3/plugins/files (requires admin token)
- Add PUT /api/v3/plugins/directory (requires admin token)
Apply to both influxdb3/core/v3 and influxdb3/enterprise/v3 specs.
chore(api): Add RemoveInternalOperations decorator to document Redocly's built-in behavior, hiding endpoints that have `x-internal: true`
chore(api): Add yarn build:api-docs
This command:
1. Changes to the api-docs directory
2. Executes the generate-api-docs.sh script to generate API
documentation HTML from the OpenAPI specs
* chore: 3.7 update
* fix(influxdb3): influxdb3 3.7 release:
- Avoid use of "retention policy" except for the storage engine
- User guide: specific heading, active voice
- Use SOURCE
* feat(influxdb3): update API docs for 3.7 release
- Add cluster-uuid response header to all write endpoints
- Document multi-member gzip payload support in ContentEncoding
- Update API version to 3.7.0 for both Core and Enterprise
- Extract cluster-uuid header to reusable component
Changes for InfluxDB 3.7 release include:
- cluster-uuid header now included in all HTTP responses
- Multi-member gzip support per RFC 1952 for write endpoints
- Compatible with v1 and v2 write endpoints
* fix(influxdb3): remove precision bug note - fixed in 3.7
Removed outdated bug note about abbreviated precision values not working
with /api/v3/write_lp endpoint. Testing confirms all abbreviated values
(ns, ms, us, s) now work correctly in InfluxDB 3.7.
Tested precision values:
- ns (nanoseconds) ✅
- ms (milliseconds) ✅
- us (microseconds) ✅
- s (seconds) ✅
* docs(influxdb3): add precision bug fix to v3.6.0 release notes
Document that abbreviated precision values (ns, ms, us, s) were fixed
in v3.6.0 to work with /api/v3/write_lp endpoint.
The fix was implemented in commit 97dafa177c and included in v3.6.0 release.
---------
Co-authored-by: Peter Barnett <peter.barnett03@gmail.com>
* docs(influxdb3): update write endpoint recommendations and add Telegraf guidance
- Update write endpoint recommendations for Core/Enterprise
- Add Telegraf output plugin guidance (v1.x and v2.x)
- Improve introductory content and formatting
- Change Note to Tip for write endpoint recommendations
- Add italics to v1/v2 for clarity
* docs(influxdb3): add precision parameter comparison and format details
- Add precision comparison table across v1, v2, v3 write APIs
- Document auto precision detection with exponential notation (5e9, 5e12, 5e15)
- Add tabbed code examples for different precision values
- Update OpenAPI specs with long-form precision values only (auto, nanosecond, microsecond, millisecond, second)
- Add timestamp conversion details for internal storage
- Use long-form precision values in all examples
Note: Currently /api/v3/write_lp only supports long forms despite source code indicating short form support.
Related to #6472 - precision parameter behavior may have bugs
Jason Stirnaman
Copilot
Joel Abshier
Scott Anderson
dependabot[bot]
Jameelah Mercer
meelahme