API reference: upstream INFLUXDB_DOCS_URL substitution pins v2 links to /influxdb/latest and emits broken URLs

[jstirnaman]

Tracking issue for defects in influxdata/openapi that surface in the InfluxDB OSS v2 API reference. The fix belongs upstream; this tracks it here because the symptom is visible on our published pages.

I couldn't file this in influxdata/openapi directly — the GitHub App has read access to that repo but no issue-write permission (403 Resource not accessible by integration). Someone with access should port this over.

All findings reproduce on influxdata/openapi master (e48e733) and docs-release/influxdb-oss (74ffccc), which is the branch api-docs/getswagger.sh fetches for OSS v2.

Root cause

influxdata/openapi PR #603 ("chore: use /latest alias for OSS URL substitutions", 2022-11-08) made {{% INFLUXDB_DOCS_URL %}} expand to https://docs.influxdata.com/influxdb/latest during OSS contract generation. Our replace-docs-url-shortcode decorator (api-docs/openapi/plugins/docs-plugin.cjs) can only rewrite shortcodes that survive into the contract — it can't touch a URL that upstream already expanded.

1. Pagination links pinned to /latest

src/common/parameters/After.yml:12 and src/common/parameters/Offset.yml:8 both source as:

For more information about pagination parameters, see [Pagination]({{% INFLUXDB_DOCS_URL %}}/api/#tag/Pagination).

and arrive in contracts/ref/oss.yml (lines 56, 85) as https://docs.influxdata.com/influxdb/latest/api/#tag/Pagination.

Effect on our v2 reference: these two links stay absolute and pinned to /latest, while every other docs link on the same page is rewritten to a relative /influxdb/v2/.... So one page mixes link styles, and the /latest ones drift to whatever the current OSS version is rather than the version the page documents.

The cloud contract expands the same source to https://docs.influxdata.com/influxdb/cloud/api/#tag/Pagination, which is version-correct — this is specific to the OSS /latest alias.

2. Duplicated path segments — broken URLs

src/oss/tags.yml:148-149 already include a version segment after the shortcode, so expansion doubles it:

Source	Generated
{{% INFLUXDB_DOCS_URL %}}/influxdb/latest/users/	https://docs.influxdata.com/influxdb/latest/influxdb/latest/users/
{{% INFLUXDB_DOCS_URL %}}/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user	https://docs.influxdata.com/influxdb/latest/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user

These land in the Users tag description on our v2 API reference.

3. Malformed shortcode never substituted

src/common/paths/me_password.yml:50 is missing the space before the closing delimiter:

- [Manage users]({{% INFLUXDB_DOCS_URL%}}/users/)

Substitution misses it, so the literal shortcode ships in contracts/ref/oss.yml:11351 and renders as raw text on our page.

Separately, 19 INFLUXDB_DOCS_URL occurrences survive unexpanded in the generated contract (lines 284, 291, 305, 318, 324, 19437, 19444, …). Those are the ones our decorator handles correctly. If leaving them for consumers is intended, then item 1 is the inconsistency to fix upstream; if not, the substitution has a wider gap than just the malformed tag.

Reproduce

git clone https://github.com/influxdata/openapi
cd openapi && git checkout docs-release/influxdb-oss   # or master

grep -c 'INFLUXDB_DOCS_URL' contracts/ref/oss.yml
grep -o 'docs.influxdata.com/influxdb/latest/\(influxdb\|latest\)/[^)" ]*' contracts/ref/oss.yml | sort -u
grep -o 'docs.influxdata.com/influxdb/latest/api/#tag/Pagination' contracts/ref/oss.yml | sort -u

Suggested upstream fix

• Correct the two src/oss/tags.yml links and the malformed tag in src/common/paths/me_password.yml. These are unambiguous source bugs.
• Decide whether the OSS contract should expand INFLUXDB_DOCS_URL at all. Preserving the shortcode — as 19 occurrences already do — lets each docs consumer substitute its own version path, which is what our pipeline expects.

Not verified

docs.influxdata.com is blocked by the egress proxy in the environment where I found this, so I haven't confirmed which of these URLs 404 versus redirect.

[jstirnaman]

Scope update — the docs-v2 half of this is fixed by #7697 (7bd1659, "move OSS v2 and Cloud v2 spec decorators to build time").

That change adds applyMirrorTransforms in post-process-specs.ts, which rewrites https://docs.influxdata.com/influxdb/latest/ and bare /influxdb/latest/ to the product root at build time. Verified by building _build/ before and after:

Build	/influxdb/latest/ links, OSS v2	Cloud v2
before	206	5
after	0	0

So item 1 (pagination links pinned to /latest) no longer affects published pages — and the real blast radius was 211 links, not the 2 pagination parameters I originally reported.

Item 3 (malformed {{% INFLUXDB_DOCS_URL%}} in src/common/paths/me_password.yml:50) is also covered downstream: the new pattern uses \s*, so it matches the tag with or without the space.

Item 2 (doubled segments from src/oss/tags.yml:148-149) turns out never to have reached docs-v2 output at all — our own api-docs/influxdb/v2/tags.yml overrides that tag's description, so the upstream text is discarded before rendering. I missed that when filing; the URLs are malformed in the contract, but we weren't publishing them.

What's left is purely upstream. All three defects are still real in influxdata/openapi's generated contracts/ref/oss.yml and still affect anyone consuming that contract directly — SDK generators, other docs consumers, anyone reading the file. But docs-v2 is no longer a motivating case, so this can be prioritized as an upstream-hygiene issue rather than a docs bug.