feat(api): implement shared OpenAPI schemas for Core and Enterprise #6687
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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]
- latest-patch.html: Replace deprecated .Store with local variable assignment. The .Store method was removed from shortcode context in newer Hugo versions. - api-endpoint.html: Add nil check for productRef lookup to prevent index errors when productKey is not in productAliases dictionary. Falls back to "influxdb" as default product reference.
- yarn build:api-docs: Generate API docs for all products - yarn build:api-docs cloud-v2: Generate for specific product - yarn build:api-docs:compile: Recompile TypeScript if modified
…. Split ui-dev subagent into hugo-, ts-, and testing-specific agents.
- Add CSS for operations list cards with method badges, paths, and summaries - Remove duplicate Overview section from list.html (was duplicating summary) - Split "Data Operations" into separate nav groups: Write data, Query data, Cache data
- 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
- Rewrite single.html for operation pages with RapiDoc integration - Simplify rapidoc.html partial for tag-based rendering - Add sidebar-nav include to sidebar.html for API navigation - Add tab-panels.html and tabs.html for content organization
- Add api-nav.ts for sidebar navigation collapse/expand - Add api-scalar.ts for Scalar API renderer integration - Add api-tabs.ts for tab switching functionality - Add api-toc.ts for table of contents generation - Register components in main.js
- Add YAML article data files for all InfluxDB products - Add sidebar-nav.html partial for API navigation rendering - Rename data directory from article-data to article_data for Hugo compatibility - Remove obsolete JSON articles file
- Update hugo.yml config for API docs settings - Simplify _api-overrides.scss (removed hardcoded content styles) - Import _api-layout.scss in styles-default.scss - Update API landing pages for Core and Enterprise with redirects - Update OpenAPI spec files - Update dependencies
- Update tests for new tag-based API page structure - Add tests for operations list rendering - Add tests for sidebar navigation groups
…tion - Header summary now shows only the first sentence from description using regex extraction with fallback to first line for descriptions without sentence-ending punctuation - Added Overview section with full description after endpoints list
- Sidebar nav now shows operations with method badges and paths instead of duplicating tag names when groups are expanded - Added background color to nav group items to match sidebar - Increased max-height for expanded groups to accommodate all operations - Added styles for operation items in sidebar nav (.api-nav-operation) - Fixed summary paragraph width by setting flex-basis to 100%
- Changed operation link font-size from 0.85rem to 0.95rem to match sidebar - Changed path code font-size from 0.75rem to 0.85rem for consistency - Adjusted method badge font-size from 0.55rem to 0.6rem for readability
…size - Add button reset styles to .api-nav-group-header for dark mode compatibility (background: none, border: none, width: 100%) - Increase operation link font-size from 0.95rem to 1rem to match sidebar nav-item font size (18px base) - Increase api-path code font-size from 0.85rem to 0.9rem
Add API nav items as children of "InfluxDB HTTP API" menu item: - New api-menu-items.html partial generates nav from data/articles.yml - Modified nested-menu.html to inject API nav for API parent menu item - Updated api_nav_groups.yml to add url for Administration group - Created Administration landing pages for Core and Enterprise - Updated .gitignore to allow hand-crafted API conceptual pages The Administration page uses layout: list and isConceptual: true to render content directly without RapiDoc wrapper.
Now that API navigation is integrated into Hugo's menu system: - Remove api-nav.ts component (no longer needed) - Remove api/sidebar-nav.html partial (replaced by api-menu-items.html) - Remove api-nav component registration from main.js - Update sidebar.html to pass siteData to nested-menu for API nav - Fix anchor ID handling for special characters (like / in operation IDs)
Remove multi-tag groups (Administration, Concepts) and flatten to single-tag groups for direct linking. Each API tag now renders as a direct nav item instead of being nested under a parent group. - Update api_nav_groups.yml to use single-tag groups only - Delete Administration landing pages (not needed without nesting) - Improve SCSS styling for API nav visibility and active states
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
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
…uality - 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
- 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
…habetically - Remove api_nav_groups.yml config file (no longer needed) - Update api-menu-items.html to derive order from article data - Sort: conceptual tags (traitTags) first, then other tags alphabetically - Reduces template from 255 to 152 lines
- Add api/section-children.html partial for API section index pages
- Update api/list.html to detect section index vs tag pages
- Add "All endpoints" nav item listing all operations sorted by method+path
- Remove {{< children >}} shortcode from API index pages (use data-driven list)
Increase font size from 0.55rem to 0.9rem for better readability while keeping the standard sans font for space efficiency.
Extract inline JavaScript from rapidoc.html into a proper TypeScript component following the established component pattern.
Remove ~230 lines of inline JavaScript and use the new api-rapidoc TypeScript component via data-component attribute instead.
Remove unused Scalar API documentation renderer: - Delete layouts/partials/api/scalar.html - Delete assets/js/components/api-scalar.ts - Simplify renderer.html to only use RapiDoc - Remove ApiScalar from main.js component registry - Remove apiRenderer config option from hugo.yml
Remove unused tabs component and partials: - Delete assets/js/components/api-tabs.ts - Delete layouts/partials/api/tabs.html - Delete layouts/partials/api/tab-panels.html - Remove ApiTabs from main.js component registry The new architecture renders content directly without tabs.
Remove tests for tabs and 3-column layout that no longer exist. Keep basic API reference tests and RapiDoc Mini component tests.
EXPERIMENTAL FINDINGS (Task 4): Tested RapiDoc's allow-authentication attribute with both render-style options to determine if it can show credential input on operation pages. Results: 1. render-style='read' + allow-authentication='true': - Auth section (#auth) exists in shadow DOM with input fields - BUT filtered out by match-paths (not visible to users) - Only matched operation shown, not full spec 2. render-style='focused' + allow-authentication='true': - Auth section completely removed from shadow DOM - Shows broken links to non-existent #auth section - Lists security schemes but no input fields CONCLUSION: RapiDoc's built-in auth UI is incompatible with match-paths filtering. When filtering to single operations, the auth section is either hidden or removed entirely. RECOMMENDATION: Implement custom auth input component (Task 5) using: - Custom TypeScript component above RapiDoc - sessionStorage for credential persistence - Integration with RapiDoc's Try it feature Code includes detailed inline documentation of findings for future reference when implementing Task 5.
- Create api-auth-input.ts TypeScript component - Store credentials in sessionStorage (secure, cleared on tab close) - Register component in main.js - Add auth form styling with dark theme support - Add component wrapper to rapidoc-mini.html template - Fix SCSS dark theme (use CSS selectors, not non-existent mixin)
- Set global security to BearerAuthentication only (best practice) - Add per-operation security to v1 endpoints (all 4 auth schemes) - Add per-operation security to v2 endpoint (Bearer + Token) - Add no-auth option for initial token creation endpoint - Fix TOC sidebar to include security scheme headings (move id to h3) - Update Authentication tag table to accurately describe endpoint support
- 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)
#6614) * chore(claude): Add claude skill for Hugo development/testing workflow. Split ui-dev subagent into hugo-, ts-, and testing-specific agents. * chore(claude): Update ui-testing agent and hugo-template-dev skill * docs(plans): add docs-cli-workflow skill design Design for a Claude Code skill that guides when to use docs create/edit CLI tools versus direct file editing. * feat(claude): add docs-cli-workflow skill Guides Claude to suggest docs create/edit CLI tools when appropriate: - Keyword-triggered activation (new page, edit URL, etc.) - Decision matrix for create vs edit vs direct editing - Suggestion templates with user confirmation - Edge case handling Addresses under-utilization of CLI scaffolding tools. * chore(claude): add console error testing pattern to hugo-template-dev skill Add Cypress pattern for catching JavaScript console errors during component testing - useful for runtime errors, JSON parsing failures, and template data binding issues.
When PR preview builds use a subdirectory baseURL like /docs-v2/pr-preview/pr-XXXX/, shortcodes that parse .RelPermalink to detect product context fail because the path has extra segments. This fix: - Adds config/pr-preview/params.yml with prPreviewPathOffset: 3 - Updates workflow to use -e pr-preview environment - Updates api-endpoint, influxdb/host, and children shortcodes to use the offset when indexing path segments - Adds nil-safety with default fallback for placeholder_host Normal builds are unaffected (offset defaults to 0).
When PR preview builds use a subdirectory baseURL like /docs-v2/pr-preview/pr-XXXX/, shortcodes that parse .RelPermalink to detect product context fail because the path has extra segments. This fix: - Adds config/pr-preview/params.yml with prPreviewPathOffset: 3 - Updates workflow to use -e pr-preview environment - Updates api-endpoint, influxdb/host, and children shortcodes to use the offset when indexing path segments - Adds nil-safety with default fallback for placeholder_host Normal builds are unaffected (offset defaults to 0).
Design for transforming /influxdb/version/ placeholders in OpenAPI spec descriptions to product-specific paths at build time.
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.
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.
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 overlay-based architecture where a shared base spec serves as the single source of truth, with product-specific overlays for Core and Enterprise. Changes: - Add shared/v3/base.yml as genericized base specification - Add Core overlay.yml (~40 lines) for product identity - Add Enterprise overlay.yml (~130 lines) with 4 exclusive endpoints: - PatchConfigureTable, PatchConfigureDatabase - GetShowLicense, PostCreateResourceToken - Add apply-overlay.js script (Redocly CLI lacks native overlay bundling) - Update getswagger.sh with bundleWithOverlay function - Regenerate ref.yml files and article data from overlays This reduces maintenance burden from ~95% duplicated content between Core (2,685 lines) and Enterprise (2,864 lines) specs. Closes #6677
Extend the overlay architecture to Cloud Dedicated and Clustered
Management APIs, sharing ~460 lines of components (schemas, responses,
security schemes) between products.
Changes:
- Add shared/management/base.yml with common components
- Add Clustered management overlay (1323 lines) with simple paths
- Add Cloud Dedicated management overlay (1617 lines) with account/cluster paths
- Fix apply-overlay.js to correctly handle array replacements
- Update getswagger.sh with bundleManagementWithOverlay function
- Regenerate management openapi.yml files from overlays
- Remove redundant content/ directories (info.yml, servers.yml, tag-groups.yml)
for Core, Enterprise, Clustered, and Cloud Dedicated management APIs
- Update Core and Enterprise overlays with full info and x-tagGroups
The management APIs have fundamentally different path structures:
- Clustered: /databases, /tokens
- Cloud Dedicated: /accounts/{accountId}/clusters/{clusterId}/databases
Overlay files now contain all product-specific customizations, eliminating
the need for separate Redocly decorator content files.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Implements overlay-based architecture for InfluxDB 3 Core and Enterprise OpenAPI specifications, reducing maintenance burden from ~95% duplicated content.
Key changes:
shared/v3/base.ymlas single source of truth (~2,715 lines)apply-overlay.jsscript (Redocly CLI lacks native overlay bundling)getswagger.shwithbundleWithOverlayfunctionEnterprise-exclusive endpoints:
PatchConfigureTable- Update table configurationPatchConfigureDatabase- Update database configurationGetShowLicense- Show license informationPostCreateResourceToken- Create resource tokensTest plan
./getswagger.sh core-v3- generates Core spec (39 operations)./getswagger.sh enterprise-v3- generates Enterprise spec (43 operations)yarn build:api-docsto regenerate article pagesCloses #6677