docs-v2/api-docs/scripts

API Documentation Generation Scripts

TypeScript-based scripts for generating Hugo data files and content pages from OpenAPI specifications.

Overview

These scripts convert OpenAPI v3 specifications into Hugo-compatible data files and content pages for all InfluxDB products.

What Gets Generated

For each product, the scripts generate:

1. OpenAPI Spec Copies (static directory):

   • influxdb-{product}.yml - YAML version of the spec
   • influxdb-{product}.json - JSON version of the spec

2. Path Group Fragments (static/openapi/{product}/paths/):

   • Separate YAML and JSON files for each API path group
   • Example: ref-api-v2-buckets.yaml and ref-api-v2-buckets.json

3. Article Metadata (data/article-data/influxdb/{product}/):

   • articles.yml - Hugo data file with article metadata
   • articles.json - JSON version for programmatic access

4. Hugo Content Pages (content/{product}/api/):

   • Markdown files generated from article data
   • One page per API path group

Quick Start

Build Scripts

Compile TypeScript to JavaScript (required before running):

yarn build:api-scripts

Generate API Pages

Generate all products:

yarn build:api-pages

Generate specific product(s):

yarn build:api-pages:product cloud-v2
yarn build:api-pages:product cloud-v2 oss-v2

Supported Products

Product ID	Description	Spec File	Content Path
cloud-v2	InfluxDB Cloud (v2 API)	api-docs/cloud/v2/ref.yml	content/influxdb/cloud/api/v2
oss-v2	InfluxDB OSS v2	api-docs/v2/ref.yml	content/influxdb/v2/api/v2
influxdb3-core	InfluxDB 3 Core	api-docs/influxdb3/core/v3/influxdb3-core-openapi.yaml	content/influxdb3/core/reference/api
influxdb3-enterprise	InfluxDB 3 Enterprise	api-docs/influxdb3/enterprise/v3/influxdb3-enterprise-openapi.yaml	content/influxdb3/enterprise/reference/api
cloud-dedicated	InfluxDB Cloud Dedicated	api-docs/influxdb3/cloud-dedicated/influxdb3-cloud-dedicated-openapi.yaml	content/influxdb/cloud-dedicated/api
cloud-serverless	InfluxDB Cloud Serverless	api-docs/influxdb3/cloud-serverless/influxdb3-cloud-serverless-openapi.yaml	content/influxdb/cloud-serverless/api
clustered	InfluxDB Clustered	api-docs/influxdb3/clustered/influxdb3-clustered-openapi.yaml	content/influxdb/clustered/api

Architecture

TypeScript Files

api-docs/scripts/
├── tsconfig.json                              # TypeScript configuration
├── generate-openapi-articles.ts               # Main orchestration script
└── openapi-paths-to-hugo-data/
    ├── index.ts                               # Core conversion logic
    └── package.json                           # Module dependencies

Compiled JavaScript

After running yarn build:api-scripts, compiled files are in:

api-docs/scripts/dist/
├── generate-openapi-articles.js
├── generate-openapi-articles.d.ts
└── openapi-paths-to-hugo-data/
    ├── index.js
    └── index.d.ts

Script Details

generate-openapi-articles.ts

Main orchestration script that processes products.

For each product, it:

1. Runs getswagger.sh to fetch/bundle the OpenAPI spec
2. Copies spec to static/openapi/influxdb-{product}.yml
3. Generates JSON version at static/openapi/influxdb-{product}.json
4. Generates path group fragments (YAML and JSON)
5. Creates article metadata (YAML and JSON)
6. Generates Hugo content pages

Usage:

node api-docs/scripts/dist/generate-openapi-articles.js [product-ids...]

# Examples:
node api-docs/scripts/dist/generate-openapi-articles.js                    # All products
node api-docs/scripts/dist/generate-openapi-articles.js cloud-v2           # Single product
node api-docs/scripts/dist/generate-openapi-articles.js cloud-v2 oss-v2    # Multiple products

Output:

📋 Processing all products...

================================================================================
Processing InfluxDB Cloud (v2 API)
================================================================================

Fetching OpenAPI spec for cloud-v2...
✓ Copied spec to static/openapi/influxdb-cloud-v2.yml
✓ Generated JSON spec at static/openapi/influxdb-cloud-v2.json

Generating OpenAPI path files in static/openapi/influxdb-cloud-v2/paths....
Generated: ref-api-v2-buckets.yaml and ref-api-v2-buckets.json
...

Generating OpenAPI article data in data/article-data/influxdb/cloud-v2...
Generated 32 articles in data/article-data/influxdb/cloud-v2

✅ Successfully processed InfluxDB Cloud (v2 API)

openapi-paths-to-hugo-data/index.ts

Core conversion library that processes OpenAPI specs.

Key Functions:

• generateHugoData(options) - Main entry point
• writePathOpenapis() - Groups paths and writes fragments
• createArticleDataForPathGroup() - Generates article metadata

Path Grouping Logic:

Paths are grouped by their base path (first 3-4 segments, excluding placeholders):

/api/v2/buckets           → api-v2-buckets
/api/v2/buckets/{id}      → api-v2-buckets (same group)
/api/v2/authorizations    → api-v2-authorizations

Output Formats:

• YAML: Hugo-compatible data files
• JSON: Programmatic access and tooling

Development

Prerequisites

• Node.js >= 16.0.0
• Yarn package manager
• TypeScript installed (via root package.json)

Setup

# Install dependencies (from repo root)
yarn install

# Or install in the openapi-paths-to-hugo-data module
cd api-docs/scripts/openapi-paths-to-hugo-data
yarn install

TypeScript Configuration

The scripts use a dedicated tsconfig.json with CommonJS output:

{
  "compilerOptions": {
    "target": "ES2021",
    "module": "CommonJS",
    "outDir": "./dist",
    "strict": true,
    ...
  }
}

Making Changes

1. Edit TypeScript files in api-docs/scripts/
2. Compile: yarn build:api-scripts
3. Test: yarn build:api-pages:product cloud-v2

Watch Mode

For active development:

cd api-docs/scripts/openapi-paths-to-hugo-data
yarn build:watch

Testing

Unit Test Example

const converter = require('./api-docs/scripts/dist/openapi-paths-to-hugo-data/index.js');

converter.generateHugoData({
  specFile: 'api-docs/influxdb/cloud/v2/ref.yml',
  dataOutPath: './test-output/paths',
  articleOutPath: './test-output/articles'
});

Verify Output

After generation, check:

1. Path fragments exist:

   ls -l static/openapi/influxdb-cloud-v2/paths/
   

2. Both formats generated:

   ls -l static/openapi/influxdb-cloud-v2/paths/*.{yaml,json}
   

3. Article data created:

   cat data/article-data/influxdb/cloud-v2/articles.yml
   cat data/article-data/influxdb/cloud-v2/articles.json
   

4. Hugo pages generated:

   ls -l content/influxdb/cloud/api/v2/
   

Troubleshooting

TypeScript Compilation Errors

# Clean and rebuild
rm -rf api-docs/scripts/dist
yarn build:api-scripts

Missing Type Definitions

cd api-docs/scripts/openapi-paths-to-hugo-data
yarn add --dev @types/js-yaml @types/node

Spec File Not Found

Make sure to run getswagger.sh first:

cd api-docs
./getswagger.sh cloud-v2 -B

Path Grouping Issues

The script groups paths by their first 3-4 segments. If you need different grouping:

1. Edit writePathOpenapis() in openapi-paths-to-hugo-data/index.ts
2. Modify the key.slice(0, 4) logic
3. Rebuild: yarn build:api-scripts

Migration from JavaScript

The original JavaScript files are preserved for reference:

• api-docs/scripts/generate-openapi-articles.js (original)
• api-docs/scripts/openapi-paths-to-hugo-data/index.js (original)

Key Improvements

1. TypeScript: Full type safety and IDE support
2. Dual Formats: Generates both YAML and JSON
3. All Products: Includes all 7 InfluxDB products
4. Better Errors: Clear error messages with product validation
5. CLI Arguments: Support for processing specific products
6. Comprehensive Logging: Progress indicators and status messages

Related Documentation

• API Docs README: api-docs/README.md - Complete API documentation workflow
• OpenAPI Plugins: api-docs/openapi/plugins/ - Custom processing plugins
• Hugo Data to Pages: hugo-data-to-pages/ - Page generation from data files

Examples

Generate Only Cloud Products

yarn build:api-pages:product cloud-v2 cloud-dedicated cloud-serverless

Generate Only InfluxDB 3 Products

yarn build:api-pages:product influxdb3-core influxdb3-enterprise

Process Single Product Manually

# Compile first
yarn build:api-scripts

# Run for specific product
node api-docs/scripts/dist/generate-openapi-articles.js oss-v2

API Reference

generateHugoData(options)

Generate Hugo data files from an OpenAPI specification.

Parameters:

• options.specFile (string) - Path to the OpenAPI spec file
• options.dataOutPath (string) - Output path for OpenAPI path fragments
• options.articleOutPath (string) - Output path for article metadata

Example:

const { generateHugoData } = require('./api-docs/scripts/dist/openapi-paths-to-hugo-data/index.js');

generateHugoData({
  specFile: 'api-docs/influxdb/cloud/v2/ref.yml',
  dataOutPath: 'static/openapi/influxdb-cloud-v2/paths',
  articleOutPath: 'data/article-data/influxdb/cloud-v2'
});

productConfigs

Map of product configurations exported from generate-openapi-articles.ts.

Type:

type ProductConfig = {
  specFile: string;      // Path to OpenAPI spec
  pagesDir: string;      // Hugo content directory
  description?: string;  // Product description
};

const productConfigs: Record<string, ProductConfig>;

Usage:

const { productConfigs } = require('./api-docs/scripts/dist/generate-openapi-articles.js');

console.log(productConfigs['cloud-v2']);
// {
//   specFile: 'api-docs/cloud/v2/ref.yml',
//   pagesDir: 'content/influxdb/cloud/api/v2',
//   description: 'InfluxDB Cloud (v2 API)'
// }

License

Same as parent docs-v2 repository (MIT).