- Add standard OpenAPI `externalDocs` field to all tags.yml files that
have `x-related` entries (uses first link as the primary doc link)
- Convert `externalDocs` to `{title, href}` objects in related links
instead of bare URL strings
- Strip `https://docs.influxdata.com` from description/summary fields
in `transformDocLinks()` so Hugo pages use relative paths
- Fix article generation reading from absolutified download spec instead
of the Hugo spec with relative links (new `hugoSpecPath` output)
- Add `externalDocs.url` support to `absolutifyLinks()` for downloads
Post-process-specs.ts now writes resolved specs (with info, servers, and
tag overlays applied) to api-docs/_build/ instead of back to source files.
Downstream consumers (Redoc HTML generation, static spec copy) read from
_build/. Source specs in api-docs/ are never mutated by the pipeline.
This makes the pipeline idempotent — running it twice produces identical
output — and keeps source spec diffs free of YAML re-serialization noise.
The clean step was deleting committed content directories (e.g.,
enterprise_influxdb/v1/api/) when running in --static-only mode.
Static-only should only copy specs to static/openapi/, not touch
content directories.
- Flatten Core/Enterprise v3/ subdirectories to product root
- Rewrite generate-api-docs.sh as clean 3-step pipeline:
post-process-specs → Redoc HTML → static spec downloads
- Add --static-only flag to generate-openapi-articles.ts
- Remove circular getswagger.sh call from generate-openapi-articles.ts
- Remove dead execCommand function and --skip-fetch flag
- Apply post-processed tag enrichments to all spec files
Flatten Cloud v2 and OSS v2 spec directories to product root with
self-documenting filenames, matching the pattern used for influxdb3 products.
Remove all 5 v1-compatibility directories — those endpoints are already
included in the main spec (tagged as v1/v2 Compatibility).
Old v1-compat URLs are preserved as Hugo aliases for redirects.
Also includes:
- Migrate inline markdown links from management API spec descriptions
into tags.yml x-related fields (Cloud Dedicated + Clustered)
- Wire post-process-specs.ts into generate-api-docs.sh build pipeline
- Fix doubled static/openapi download filenames
- Update project plan with design decisions
Drop redundant version subdirectories and use self-documenting
filenames for 5 products:
v2-compat influxdb3:
cloud-dedicated/v2/ref.yml → cloud-dedicated/influxdb3-cloud-dedicated-openapi.yaml
cloud-serverless/v2/ref.yml → cloud-serverless/influxdb3-cloud-serverless-openapi.yaml
clustered/v2/ref.yml → clustered/influxdb3-clustered-openapi.yaml
v1:
influxdb/v1/v1/ref.yml → influxdb/v1/influxdb-oss-v1-openapi.yaml
enterprise_influxdb/v1/v1/ref.yml → enterprise_influxdb/v1/influxdb-enterprise-v1-openapi.yaml
Update .config.yml, getswagger.sh, and generate-openapi-articles.ts
to reference new paths.
Extract all api-docs/ changes from feat-api-uplift into a standalone
branch for independent testing and merging to master.
Changes include:
- Updated generation scripts (generate-openapi-articles.ts,
openapi-paths-to-hugo-data/index.ts) for Hugo-native templates
- Removed dead x-tagGroups infrastructure (decorator, config files)
- Updated Core and Enterprise specs with tag descriptions, x-related
links, and Cache Data tag split
- Added v1 product configs and specs (OSS v1, Enterprise v1)
- Updated getswagger.sh for renamed spec files
- Updated generate-api-docs.sh with clean regeneration support
Jason Stirnaman