influxdata / influxdata/docs-v2

api-docs: tags.yml links to a QuerystringAuthentication anchor that no longer exists in the v2 and Cloud specs

Open
#7,667 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
82
Forks
326
Avg merge
1d 1h
Merged PRs (30d)
82

Description

`api-docs/influxdb/v2/tags.yml:9` and `api-docs/influxdb/cloud/tags.yml:9` both contain:

```markdown
- [Querystring authentication](#section/Authentication/QuerystringAuthentication)
```

That anchor is generated from `components.securitySchemes`. Current upstream `contracts/ref/oss.yml` on `influxdata/openapi` `docs-release/influxdb-oss` declares only `BasicAuthentication` and `TokenAuthentication` — no `QuerystringAuthentication`. So the link has no target.

## Verification

Running the pipeline against current sources:

```sh
cd api-docs && bash getswagger.sh v2
cd .. && node api-docs/scripts/dist/post-process-specs.js

python3 -c "import yaml;print(sorted(yaml.safe_load(open('api-docs/_build/influxdb/v2/influxdb-oss-v2-openapi.yaml'))['components']['securitySchemes']))"
# ['BasicAuthentication', 'TokenAuthentication']

grep -n QuerystringAuthentication api-docs/_build/influxdb/v2/influxdb-oss-v2-openapi.yaml
# 76: - [Querystring authentication](#section/Authentication/QuerystringAuthentication)
```

One occurrence in the built spec — the `tags.yml` link itself, with nothing to point at.

## Why the currently-committed spec hides this

`api-docs/influxdb/v2/influxdb-oss-v2-openapi.yaml` still carries a `QuerystringAuthentication` entry under `components.securitySchemes`, left over from an older upstream contract. But even there it has **zero `$ref`s** and is absent from the top-level `security:` block, so it's already an orphan definition. Whether the rendered page currently produces a working anchor from an unreferenced scheme is worth checking; either way, the next regeneration removes the definition and the link definitely breaks.

Note this is unrelated to #7175, which is about per-tag page URLs not resolving in the built site.

## Fix options

1. Drop the bullet from both `tags.yml` files, if querystring auth is genuinely no longer supported for these APIs.
2. Restore `QuerystringAuthentication` upstream in `influxdata/openapi` if the v1-compatibility endpoints still accept `?u=&p=`, and keep the link.

Option 2 needs a product answer — the v1-compat `/query` and `/write` operations in the OSS v2 spec do still document inline `u` and `p` query parameters, which suggests the auth method exists but is no longer declared as a security scheme.

The InfluxDB 3 specs (`core`, `enterprise`, `clustered`, `cloud-dedicated`, `cloud`) all still define `QuerystringAuthentication` and reference it from `security:`, so this only affects the v2 and Cloud v2 specs.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with api-docs/influxdb/v2/tags.yml and api-docs/influxdb/cloud/tags.yml, then compare their security schemes with contracts/ref/oss.yml from the documented upstream branch. Run the getswagger.sh and post-process-specs.js commands to reproduce the missing anchor, and resolve whether the querystring authentication link should be removed or restored upstream. Done means the chosen behavior is reflected in both specs without a dangling QuerystringAuthentication link.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
api, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.