Generate curl examples at Hugo template time from OpenAPI specs, with
server URL variable resolution, $ref handling, and JSON body generation
from schema properties. Add "Ask AI about this example" links using
existing Kapa integration. Add client library related link to all
InfluxDB 3 API tag pages. Improve visual separation between operations
with distinct badge colors and response body indentation.
Remove all RapiDoc-specific code from styles and JavaScript:
- Delete rapi-doc::part() CSS selectors from _api-layout.scss
- Delete dead auth modal styles from _api-security-schemes.scss
- Delete api-auth-input.ts component (RapiDoc "Try it" integration)
- Delete static/css/rapidoc-custom.css (unused)
- Remove setupRapiDocNavigation() from api-toc.ts
- Update comments to remove RapiDoc references
Rename _api-hugo-native.scss to _api-operations.scss since
Hugo-native is now the standard (not a POC).
- Replace #operation/OperationId links with page-based URLs
(e.g., #operation/GetLegacyQuery → /influxdb3/clustered/api/query-data/)
- Fix Quick start menu ordering by sorting nav items by weight
- Add default weight (100) to all articles for consistent sorting
- Quick start gets weight 1 to appear first in navigation
- Add x-influxdatadocs-related support in TypeScript for tags and operations
- Remove inline "Related guides" sections from OpenAPI descriptions
- Move related links to structured x-influxdatadocs-related arrays
- Add weight support for Quick start pages (weight: 1) to appear first in nav
- Update clustered and cloud-dedicated v2/ref.yml specs
- Add tag-based article generation with operation grouping
- Support x-influxdata-related field for related content links
- Improve spec transformation with documentation link handling
- Add JSON output alongside YAML for article data
- Enhance path and tag spec generation for per-operation pages
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.
- 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]
Jason Stirnaman