Update code comments and documentation to accurately reflect that
the API documentation uses RapiDoc, not Scalar:
- api-docs/scripts/generate-openapi-articles.ts: Update JSDoc comments
- api-docs/scripts/dist/generate-openapi-articles.js: Update compiled version
- assets/js/components/api-toc.ts: Update implementation comment
- .claude/agents/ts-component-dev.md: Update component reference
- .claude/skills/hugo-template-dev/SKILL.md: Update component reference
The implementation uses RapiDoc throughout, so these comments needed
to be corrected for accuracy.
Fixed two issues causing Hugo warnings about duplicate menu entries:
1. Path generation bug: apiPathToSlug returns 'api/v3/...' for paths
starting with '/api/', but the generator always prepended 'api/',
creating 'api/api/v3/...' paths.
Fix: Only add 'api/' prefix if path doesn't already start with it.
2. Config inconsistency: cloud-dedicated, cloud-serverless, and clustered
had '/api' in pagesDir while core/enterprise didn't. The function
always adds '/api', causing double prefixes for some products.
Fix: Removed '/api' from pagesDir for affected products to match
core/enterprise pattern.
Add showSecuritySchemes field handling to generate-openapi-articles.ts
to ensure the flag is written to content frontmatter. Regenerate API
docs for cloud-dedicated and clustered products.
Add showSecuritySchemes field to Article interface and automatically
set it to true for Authentication tag pages. This ensures the Security
Schemes section renders on authentication pages after API docs are
regenerated.
Transform /influxdb/version/ placeholders in OpenAPI spec description
and summary fields to product-specific paths at build time.
- Add deriveProductPath() to extract product path from spec location
- Add transformDocLinks() to recursively transform markdown links
- Add validateDocLinks() with --validate-links CLI flag for checking
- Integrate transformation into processProduct() workflow
- Add placeholder links to Authorization header descriptions
The product path is derived from the spec file location, so
api-docs/influxdb3/core/v3/ref.yml produces /influxdb3/core paths.
- Convert collapsible auth panel to popover UI triggered by
"Set credentials" button positioned above RapiDoc
- Filter auth schemes based on API path:
- /api/v3/* endpoints: Bearer only
- /api/v2/* endpoints: Bearer + Token
- /write, /query (v1): All 4 schemes
- Fix "Authentication Not Required" bug by adding global security
field to path-specific OpenAPI specs
- Change RapiDoc --blue CSS variable to green so status text and
type links don't look like clickable links
- Add explicit button styling for Apply/Clear in popover
- Hide RapiDoc's built-in auth section (use custom popover instead)
- Update api_nav_groups.yml to use "Auth token" instead of "Token"
- Remove x-tagGroups from Core and Enterprise specs (Redoc-specific, not needed for RapiDoc)
- Add migration notes to plan document for future product migrations
- Restore original RapiDoc match-paths format (method /path) for proper filtering
- Restrict operation tags to primary tag in tag-specific specs to prevent duplicates
- Rename Token tag to Auth token for clarity in Core and Enterprise specs
- Remove Table tag from cache operations (distinct_cache, last_cache)
- Add build script combining API docs, Hugo, and Markdown generation
- Skip summary rendering for conceptual pages
- Add isConceptual check to hide operations in nav for conceptual pages
The feature is shippable, but needs a few small fixes and we'll need to update or alias all API docs links for Core and Ent3.
- Add rapidoc-mini.ts TypeScript component with CDN loading and theme sync
- Add api-operation layout for standalone operation pages
- Add rapidoc-mini.html partial for reusable RapiDoc rendering
- Add rapidoc-custom.css for RapiDoc style overrides
- Register rapidoc-mini component in main.js
- Add article data for cloud-dedicated and clustered products
- Update API reference Cypress tests
Add visual badges to distinguish v1-compatible and v2-compatible API
endpoints in the sidebar navigation. This helps users migrating from
InfluxDB v1 or v2 quickly identify which compatibility layer each
endpoint belongs to.
Changes:
- Add x-compatibility-version extension to compatibility operations
- Add externalDocs links to reduce verbose descriptions in specs
- Update generator to extract compatVersion and externalDocs fields
- Display colored badges (purple for v1, cyan for v2) in sidebar nav
- Strip redundant "(v1-compatible)" text when badge is shown
- Add hover tooltips explaining compatibility context
- Add support for tag-based article generation with operations metadata
- Generate articles.yml data files with tag, menuName, and isConceptual fields
- Include operations array in frontmatter for tag pages
Replace legacy API documentation approach with modern Scalar-based rendering:
## Architecture Changes
- Add renderer abstraction (`layouts/partials/api/`) supporting Scalar and RapiDoc
- Create `api` layout type for API reference pages (single.html, list.html)
- Configure renderer via `site.Params.apiRenderer` (default: scalar)
## OpenAPI Processing Pipeline (TypeScript)
- `api-docs/scripts/generate-openapi-articles.ts` - Main generation script
- `api-docs/scripts/openapi-paths-to-hugo-data/` - OpenAPI to Hugo data converter
- Generates per-endpoint path fragments for AI agent access
- Creates Hugo content pages with `type: api` frontmatter
## AI Agent Accessibility
- Full specs at `/openapi/influxdb-{product}.yml` and `.json`
- Per-endpoint fragments at `/openapi/influxdb-{product}/paths/`
- `<link rel="alternate">` tags in HTML for machine discovery
## Scalar Features
- Dark/light theme support synchronized with site theme
- InfluxData brand colors
- Responsive layout
- Download link for OpenAPI spec
## Products Supported
- cloud-v2, oss-v2
- influxdb3-core, influxdb3-enterprise
- cloud-dedicated, cloud-serverless, clustered
Usage: node api-docs/scripts/dist/generate-openapi-articles.js [product]
Claude
Jason Stirnaman