influxdata / influxdata/docs-v2
API reference: upstream INFLUXDB_DOCS_URL substitution pins v2 links to /influxdb/latest and emits broken URLs
- Dominant language
- JavaScript
- Stars
- 82
- Forks
- 326
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 82
Description
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:
```yaml
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:
```yaml
- [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
```sh
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.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start in influxdata/openapi on the docs-release/influxdb-oss branch, reading src/oss/tags.yml, src/common/paths/me_password.yml, and the substitution behavior exercised by api-docs/getswagger.sh. Run the provided grep checks against contracts/ref/oss.yml and compare the generated links with the surviving shortcode occurrences. Done means the upstream behavior and intended OSS URL expansion are decided, the identified source defects are addressed, and the generated contract no longer contains the reported malformed or duplicated URLs.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, openapi, yaml
- Domain
- api, documentation, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100