refactor(api-docs): unified post-processor, directory flatten, CI build step

[jstirnaman]

Summary

Restructures the api-docs/ directory and build pipeline to support Hugo-native API reference pages. Replaces Redocly-specific infrastructure with a standalone TypeScript post-processor, flattens all version subdirectories, and adds per-product tag configurations.

• Replace Redocly set-info, set-servers, and set-tag-groups decorators with a unified TypeScript post-processor (post-process-specs.ts)
• Flatten all version subdirectories (e.g., influxdb3/core/v3/ → influxdb3/core/) — every product stores its spec at the product root
• Remove all v1-compatibility/ directories (5 products) — endpoints already exist in main specs
• Add per-product tags.yml configs with descriptions, x-traitTag support, and x-related links for all 11 products
• Write resolved specs to _build/ (gitignored) instead of mutating source files — pipeline is idempotent
• Add TypeScript compilation step to CircleCI and PR preview workflows
• Add --static-only mode for generating download files without Redoc HTML
• Migrate inline markdown links from management spec descriptions to tags.yml x-related
• Enforce one-tag-per-operation across all specs
• Add v1 product specs (OSS v1, Enterprise v1)

Build pipeline

1. getswagger.sh          — fetch and bundle specs with Redocly (skip for management specs)
2. post-process-specs.ts   — apply info/servers overlays + tag configs → write to _build/
3. generate-api-docs.sh    — generate Redoc HTML from _build/ specs
4. generate-openapi-articles.ts --static-only — copy specs to static/openapi/ as YAML + JSON

Source specs in api-docs/ are never mutated during generation.

Directory layout (after)

api-docs/influxdb3/core/influxdb3-core-openapi.yaml
api-docs/influxdb3/enterprise/influxdb3-enterprise-openapi.yaml
api-docs/influxdb3/cloud-dedicated/influxdb3-cloud-dedicated-openapi.yaml
api-docs/influxdb3/cloud-dedicated/management/openapi.yml
api-docs/influxdb3/cloud-serverless/influxdb3-cloud-serverless-openapi.yaml
api-docs/influxdb3/clustered/influxdb3-clustered-openapi.yaml
api-docs/influxdb3/clustered/management/openapi.yml
api-docs/influxdb/cloud/influxdb-cloud-v2-openapi.yaml
api-docs/influxdb/v2/influxdb-oss-v2-openapi.yaml
api-docs/influxdb/v1/influxdb-oss-v1-openapi.yaml
api-docs/enterprise_influxdb/v1/influxdb-enterprise-v1-openapi.yaml

Verification

Step	Command	Result
TypeScript compile	npx tsc --project api-docs/scripts/tsconfig.json	Exit 0
Post-process specs	node api-docs/scripts/dist/post-process-specs.js	Exit 0, 11 specs → _build/
Static spec copy	node api-docs/scripts/dist/generate-openapi-articles.js --static-only	Exit 0, 22 files → static/openapi/
Unit tests	node api-docs/scripts/dist/test-post-process-specs.js	13 tests, 41 assertions
No x-tagGroups	grep -r 'x-tagGroups' api-docs/ --include='*.yml' --include='*.yaml'	No matches
No v1-compat dirs	find api-docs -name 'v1-compatibility' -type d	No matches
No version subdirs	find api-docs -maxdepth 4 -name 'v2' -o -name 'v3' | grep -v node_modules	No matches

Key changes

New files

• api-docs/scripts/post-process-specs.ts — unified spec post-processor (info, servers, tags)
• api-docs/scripts/test-post-process-specs.ts — 13 tests, 41 assertions
• 11 tags.yml files — per-product tag configs with descriptions and x-related links
• v1 product configs and specs (OSS v1, Enterprise v1)

Removed

• x-tagGroups vendor extension from all specs (dead — Hugo-native layout ignores it)
• set-tag-groups.cjs decorator and 10 tag-groups.yml config files
• All 5 v1-compatibility/ directories
• All version subdirectories (v2/, v3/, v1/v1/)

CI changes

• .circleci/config.yml — TypeScript build step before API doc generation
• .github/workflows/pr-preview.yml — TypeScript build step, commit status signaling for preview coordination
• .github/workflows/doc-review.yml — updated for api-docs-only PRs
• .github/scripts/detect-preview-pages.js — handles API-only PRs

Test plan

• npx tsc --project api-docs/scripts/tsconfig.json compiles without errors
• node api-docs/scripts/dist/post-process-specs.js processes all 11 specs
• node api-docs/scripts/dist/generate-openapi-articles.js --static-only produces 22 download files
• cd api-docs && bash generate-api-docs.sh generates Redoc HTML for all products
• npx hugo --quiet builds without template errors
• Spot-check generated tag pages for descriptions and x-related links

[jstirnaman]

Code review

Found 2 issues:

1. yarn build:api-docs --validate-links is documented in api-docs/README.md but does not work. package.json defines build:api-docs as cd api-docs && bash generate-api-docs.sh, which does not accept or forward --validate-links. The flag is implemented in generate-openapi-articles.ts but the documented invocation path silently ignores it. (CLAUDE.md says: "No phantom features — Don't document or validate features that aren't implemented")

docs-v2/api-docs/README.md

Lines 475 to 483 in 6bb7d25

	### Link validation
	Run with the `--validate-links` flag to check for broken links:
	```bash
	yarn build:api-docs --validate-links
	```
	This validates that transformed links point to existing Hugo content files and warns about any broken links.

2. Stale-tag warning in post-process-specs.ts fires for every trait tag (x-traitTag: true). Trait tags are supplementary documentation with no operations by design, so each one triggers WARN: config tag '...' not found in spec operations. With 50 trait tags across all products, every build produces 50 spurious warnings that mask legitimate stale-tag alerts. Add a guard: if (tagsCfg.tags[cfgKey]?.['x-traitTag']) continue; before the warning. (bug: stale-tag check does not account for trait tags)

docs-v2/api-docs/scripts/post-process-specs.ts

Lines 295 to 301 in 6bb7d25

	// Warn: config references a tag not in the spec
	for (const cfgKey of configKeys) {
	const effectiveName = tagsCfg.tags[cfgKey]?.rename ?? cfgKey;
	if (!operationTags.has(cfgKey) && !operationTags.has(effectiveName)) {
	log(`WARN ${label}: config tag '${cfgKey}' not found in spec operations`);
	}
	}

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[jstirnaman]

Code review (commit 9a385c6)

Found 1 issue (fixed in 2e9ac17):

1. Orphaned closing parentheses from Redoc link stripping. The regex that removed #tag/Authorizations-(API-tokens) anchor links consumed the inner ) as part of the link target, leaving the outer ) behind. This produced broken tag references (- Authorizations) instead of - Authorizations (API tokens)) and malformed prose (\/api/v2/authorizations`) toinstead of`/api/v2/authorizations` to`). 19 occurrences fixed.

https://github.com/influxdata/docs-v2/blob/2e9ac178fead2f4c16b97e3aff8b64e4b389a28e/api-docs/influxdb3/cloud-serverless/influxdb3-cloud-serverless-openapi.yaml#L1469-L1471

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}