Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

refactor(api): move Related guides to x-influxdatadocs-related field 

- Add x-influxdatadocs-related support in TypeScript for tags and operations
- Remove inline "Related guides" sections from OpenAPI descriptions
- Move related links to structured x-influxdatadocs-related arrays
- Add weight support for Quick start pages (weight: 1) to appear first in nav
- Update clustered and cloud-dedicated v2/ref.yml specs
claude/api-code-samples-plan-MEkQO
Jason Stirnaman 2026-02-06 13:48:31 -06:00
parent 36ee2866e7
commit da077a21b4
7 changed files with 1624 additions and 1764 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
api-docs/influxdb3/cloud-dedicated/v2/ref.yml
View File

@ -127,12 +127,10 @@ tags:
using **InfluxQL** and retrieve data in **CSV** or **JSON** format.
- The `/api/v2/query` endpoint can't query InfluxDB 3 Cloud Dedicated.
- _Flight + gRPC_ clients can query using **SQL** or **InfluxQL** and retrieve data in **Arrow** format.
#### Related guides
- [Get started querying InfluxDB](/influxdb3/cloud-dedicated/get-started/query/)
- [Execute queries](/influxdb3/cloud-dedicated/query-data/execute-queries/)
name: Query data
x-influxdatadocs-related:
- /influxdb3/cloud-dedicated/get-started/query/
- /influxdb3/cloud-dedicated/query-data/execute-queries/
- description: |
Get started with the InfluxDB 3 Cloud Dedicated API:
@ -302,14 +300,12 @@ paths:
- Use the [`/write` endpoint](#operation/PostLegacyWrite) for [InfluxDB v1 parameter compatibility](/influxdb3/cloud-dedicated/guides/api-compatibility/v1/).
- Use the [`/api/v2/write` endpoint](#operation/PostWrite) for [InfluxDB v2 parameter compatibility](/influxdb3/cloud-dedicated/guides/api-compatibility/v2/).
#### Related guides
- [Get started writing data](/influxdb3/cloud-dedicated/get-started/write/)
- [Write data](/influxdb3/cloud-dedicated/write-data/)
- [Best practices for writing data](/influxdb3/cloud-dedicated/write-data/best-practices/)
- [Troubleshoot issues writing data](/influxdb3/cloud-dedicated/write-data/troubleshoot/)
operationId: PostWrite
x-influxdatadocs-related:
- /influxdb3/cloud-dedicated/get-started/write/
- /influxdb3/cloud-dedicated/write-data/
- /influxdb3/cloud-dedicated/write-data/best-practices/
- /influxdb3/cloud-dedicated/write-data/troubleshoot/
parameters:
- $ref: '#/components/parameters/TraceSpan'
- description: |
@ -357,10 +353,6 @@ paths:
- Returns only `application/json` for format and limit errors.
- Returns only `text/html` for some quota limit errors.
#### Related guides
- [Troubleshoot issues writing data](/influxdb3/cloud-dedicated/write-data/troubleshoot/)
in: header
name: Accept
schema:
@ -422,10 +414,6 @@ paths:
1. Use [gzip](https://www.gzip.org/) to compress the line protocol data.
2. In your request, send the compressed data and the
`Content-Encoding: gzip` header.
#### Related guides
- [Best practices for optimizing writes](/influxdb3/cloud-dedicated/write-data/best-practices/optimize-writes/)
required: true
responses:
'201':
@ -642,13 +630,11 @@ paths:
- Use the [`/write` endpoint](#operation/PostLegacyWrite) for [InfluxDB v1 parameter compatibility](/influxdb3/cloud-dedicated/guides/api-compatibility/v1/).
- Use the [`/api/v2/write` endpoint](#operation/PostWrite) for [InfluxDB v2 parameter compatibility](/influxdb3/cloud-dedicated/guides/api-compatibility/v2/).
#### Related guides
- [Get started writing data](/influxdb3/cloud-dedicated/get-started/write/)
- [Write data](/influxdb3/cloud-dedicated/write-data/)
- [Best practices for writing data](/influxdb3/cloud-dedicated/write-data/best-practices/)
- [Troubleshoot issues writing data](/influxdb3/cloud-dedicated/write-data/troubleshoot/)
x-influxdatadocs-related:
- /influxdb3/cloud-dedicated/get-started/write/
- /influxdb3/cloud-dedicated/write-data/
- /influxdb3/cloud-dedicated/write-data/best-practices/
- /influxdb3/cloud-dedicated/write-data/troubleshoot/
parameters:
- $ref: '#/components/parameters/TraceSpan'
- description: The InfluxDB 1.x username to authenticate the request.
@ -1086,9 +1072,7 @@ components:
Annotation rows to include in the results.
An _annotation_ is metadata associated with an object (column) in the data model.
#### Related guides
- See [Annotated CSV annotations](/influxdb3/cloud-dedicated/reference/syntax/annotated-csv/#annotations) for examples and more information.
See [Annotated CSV annotations](/influxdb3/cloud-dedicated/reference/syntax/annotated-csv/#annotations) for examples and more information.
For more information about **annotations** in tabular data,
see [W3 metadata vocabulary for tabular data](https://www.w3.org/TR/2015/REC-tabular-data-model-20151217/#columns).
@ -1852,9 +1836,7 @@ components:
- Doesn't use `shardGroupDurationsSeconds`.
#### Related guides
- InfluxDB [shards and shard groups](/influxdb3/cloud-dedicated/reference/internals/shards/)
For more information, see [shards and shard groups](/influxdb3/cloud-dedicated/reference/internals/shards/).
format: int64
type: integer
type:
@ -2018,10 +2000,8 @@ components:
- **`DATABASE_NAME`**: your InfluxDB 3 Cloud Dedicated database
- **`DATABASE_TOKEN`**: a database token with sufficient permissions to the database
#### Related guides
- [Authenticate v1 API requests](/influxdb3/cloud-dedicated/guides/api-compatibility/v1/)
- [Manage tokens](/influxdb3/cloud-dedicated/admin/tokens/)
For more information, see [Authenticate v1 API requests](/influxdb3/cloud-dedicated/guides/api-compatibility/v1/)
and [Manage tokens](/influxdb3/cloud-dedicated/admin/tokens/).
QuerystringAuthentication:
type: apiKey
in: query
@ -2074,10 +2054,8 @@ components:
- **`DATABASE_NAME`**: the database to query
- **`DATABASE_TOKEN`**: a database token with sufficient permissions to the database
#### Related guides
- [Authenticate v1 API requests](/influxdb3/cloud-dedicated/guides/api-compatibility/v1/)
- [Manage tokens](/influxdb3/cloud-dedicated/admin/tokens/)
For more information, see [Authenticate v1 API requests](/influxdb3/cloud-dedicated/guides/api-compatibility/v1/)
and [Manage tokens](/influxdb3/cloud-dedicated/admin/tokens/).
BearerAuthentication:
type: http
scheme: bearer
@ -2134,9 +2112,7 @@ components:
--data-binary 'home,room=kitchen temp=72 1463683075'
```
### Related guides
- [Manage tokens](/influxdb3/cloud-dedicated/admin/tokens/)
For more information, see [Manage tokens](/influxdb3/cloud-dedicated/admin/tokens/).
in: header
name: Authorization
type: apiKey

62
api-docs/influxdb3/clustered/v2/ref.yml
View File

@ -127,12 +127,10 @@ tags:
using **InfluxQL** and retrieve data in **CSV** or **JSON** format.
- The `/api/v2/query` endpoint can't query InfluxDB 3 Clustered.
- _Flight + gRPC_ clients can query using **SQL** or **InfluxQL** and retrieve data in **Arrow** format.
#### Related guides
- [Get started querying InfluxDB](/influxdb3/clustered/get-started/query/)
- [Execute queries](/influxdb3/clustered/query-data/execute-queries/)
name: Query data
x-influxdatadocs-related:
- /influxdb3/clustered/get-started/query/
- /influxdb3/clustered/query-data/execute-queries/
- description: |
Get started with the InfluxDB 3 Clustered API:
@ -283,14 +281,12 @@ paths:
To ensure that InfluxDB Cloud handles writes in the order you request them,
wait for a success response (HTTP `2xx` status code) before you send the next request.
#### Related guides
- [Get started writing data](/influxdb3/clustered/get-started/write/)
- [Write data](/influxdb3/clustered/write-data/)
- [Best practices for writing data](/influxdb3/clustered/write-data/best-practices/)
- [Troubleshoot issues writing data](/influxdb3/clustered/write-data/troubleshoot/)
operationId: PostWrite
x-influxdatadocs-related:
- /influxdb3/clustered/get-started/write/
- /influxdb3/clustered/write-data/
- /influxdb3/clustered/write-data/best-practices/
- /influxdb3/clustered/write-data/troubleshoot/
parameters:
- $ref: '#/components/parameters/TraceSpan'
- description: |
@ -336,10 +332,6 @@ paths:
- Returns only `application/json` for format and limit errors.
- Returns only `text/html` for some quota limit errors.
#### Related guides
- [Troubleshoot issues writing data](/influxdb3/clustered/write-data/troubleshoot/)
in: header
name: Accept
schema:
@ -401,10 +393,6 @@ paths:
1. Use [gzip](https://www.gzip.org/) to compress the line protocol data.
2. In your request, send the compressed data and the
`Content-Encoding: gzip` header.
#### Related guides
- [Best practices for optimizing writes](/influxdb3/clustered/write-data/best-practices/optimize-writes/)
required: true
responses:
'204':
@ -727,15 +715,13 @@ paths:
To ensure that InfluxDB handles writes in the order you request them,
wait for a success response (HTTP `2xx` status code) before you send the next request.
#### Related guides
- [Write data with the InfluxDB API](/influxdb3/clustered/get-started/write/)
- [Optimize writes to InfluxDB](/influxdb3/clustered/write-data/best-practices/optimize-writes/)
- [Troubleshoot issues writing data](/influxdb3/clustered/write-data/troubleshoot/)
summary: Write data using the InfluxDB v1 HTTP API
tags:
- Write data
x-influxdatadocs-related:
- /influxdb3/clustered/get-started/write/
- /influxdb3/clustered/write-data/best-practices/optimize-writes/
- /influxdb3/clustered/write-data/troubleshoot/
components:
parameters:
TraceSpan:
@ -1064,9 +1050,7 @@ components:
Annotation rows to include in the results.
An _annotation_ is metadata associated with an object (column) in the data model.
#### Related guides
- See [Annotated CSV annotations](/influxdb3/clustered/reference/syntax/annotated-csv/#annotations) for examples and more information.
See [Annotated CSV annotations](/influxdb3/clustered/reference/syntax/annotated-csv/#annotations) for examples and more information.
For more information about **annotations** in tabular data,
see [W3 metadata vocabulary for tabular data](https://www.w3.org/TR/2015/REC-tabular-data-model-20151217/#columns).
@ -1830,9 +1814,7 @@ components:
- Doesn't use `shardGroupDurationsSeconds`.
#### Related guides
- InfluxDB [shards and shard groups](/influxdb3/clustered/reference/internals/shards/)
For more information, see [shards and shard groups](/influxdb3/clustered/reference/internals/shards/).
format: int64
type: integer
type:
@ -2002,10 +1984,8 @@ components:
- **`DATABASE_NAME`**: your InfluxDB 3 Clustered database
- **`DATABASE_TOKEN`**: a database token with sufficient permissions to the database
#### Related guides
- [Authenticate v1 API requests](/influxdb3/clustered/guides/api-compatibility/v1/)
- [Manage tokens](/influxdb3/clustered/admin/tokens/)
For more information, see [Authenticate v1 API requests](/influxdb3/clustered/guides/api-compatibility/v1/)
and [Manage tokens](/influxdb3/clustered/admin/tokens/).
QuerystringAuthentication:
type: apiKey
in: query
@ -2058,10 +2038,8 @@ components:
- **`DATABASE_NAME`**: the database to query
- **`DATABASE_TOKEN`**: a database token with sufficient permissions to the database
#### Related guides
- [Authenticate v1 API requests](/influxdb3/clustered/guides/api-compatibility/v1/)
- [Manage tokens](/influxdb3/clustered/admin/tokens/)
For more information, see [Authenticate v1 API requests](/influxdb3/clustered/guides/api-compatibility/v1/)
and [Manage tokens](/influxdb3/clustered/admin/tokens/).
BearerAuthentication:
type: http
scheme: bearer
@ -2118,9 +2096,7 @@ components:
--data-binary 'home,room=kitchen temp=72 1463683075'
```
### Related guides
- [Manage tokens](/influxdb3/clustered/admin/tokens/)
For more information, see [Manage tokens](/influxdb3/clustered/admin/tokens/).
in: header
name: Authorization
type: apiKey

1853
api-docs/scripts/dist/generate-openapi-articles.js vendored
View File

File diff suppressed because it is too large Load Diff

1355
api-docs/scripts/dist/openapi-paths-to-hugo-data/index.js vendored
View File

File diff suppressed because it is too large Load Diff

7
api-docs/scripts/generate-openapi-articles.ts
View File

@ -441,6 +441,7 @@ function generateTagPagesFromArticleData(
staticFilePath?: string;
operations?: OperationMeta[];
related?: string[];
weight?: number;
};
}>;
};
@ -571,13 +572,16 @@ All {{% product-name %}} API endpoints, sorted by path.
const title = article.fields.title || article.fields.name || article.path;
const isConceptual = article.fields.isConceptual === true;
// Determine weight: use article.fields.weight if set, otherwise default to 100
const weight = article.fields.weight ?? 100;
const frontmatter: Record<string, unknown> = {
title,
description: article.fields.description || `API reference for ${title}`,
type: 'api',
layout: isConceptual ? 'single' : 'list',
staticFilePath: article.fields.staticFilePath,
weight: 100,
weight,
// Tag-based fields
tag: article.fields.tag,
isConceptual,
@ -734,6 +738,7 @@ function generatePathPages(options: GeneratePathPagesOptions): void {
staticFilePath?: string;
operations?: OperationMeta[];
related?: string[];
weight?: number;
};
}>;
};

45
api-docs/scripts/openapi-paths-to-hugo-data/index.ts
View File

@ -41,6 +41,8 @@ interface Operation {
externalDocs?: ExternalDocs;
/** Compatibility version for migration context (v1 or v2) */
'x-compatibility-version'?: string;
/** Related documentation links (replaces inline "Related guides" sections) */
'x-influxdatadocs-related'?: string[];
[key: string]: unknown;
}
@ -216,6 +218,8 @@ interface Tag {
externalDocs?: ExternalDocs;
/** Indicates this is a conceptual/supplementary tag (no operations) */
'x-traitTag'?: boolean;
/** Related documentation links (replaces inline "Related guides" sections) */
'x-influxdatadocs-related'?: string[];
[key: string]: unknown;
}
@ -235,6 +239,8 @@ interface OperationMeta {
description: string;
url: string;
};
/** Related documentation links */
related?: string[];
}
/**
@ -277,6 +283,8 @@ interface Article {
menuGroup?: string;
/** Operations metadata for TOC generation */
operations?: OperationMeta[];
/** Page weight for ordering in navigation */
weight?: number;
};
}
@ -457,6 +465,14 @@ function extractOperationsByTag(
};
}
// Extract x-influxdatadocs-related if present
if (
operation['x-influxdatadocs-related'] &&
Array.isArray(operation['x-influxdatadocs-related'])
) {
opMeta.related = operation['x-influxdatadocs-related'];
}
// Add operation to each of its tags
(operation.tags || []).forEach((tag) => {
if (!tagOperations.has(tag)) {
@ -1089,17 +1105,34 @@ function createArticleDataForTag(
article.fields.showSecuritySchemes = true;
}
// Aggregate unique externalDocs URLs from operations into article-level related
// Set custom weight for Quick start to appear first in nav
if (tagName === 'Quick start') {
article.fields.weight = 1;
}
// Aggregate unique related URLs from multiple sources into article-level related
// This populates Hugo frontmatter `related` field for "Related content" links
const relatedUrls = new Set<string>();
// First check tag-level externalDocs
// First check tag-level x-influxdatadocs-related
if (tagMeta?.['x-influxdatadocs-related']) {
(tagMeta['x-influxdatadocs-related'] as string[]).forEach((url) =>
relatedUrls.add(url)
);
}
// Then check tag-level externalDocs (legacy single link)
if (tagMeta?.externalDocs?.url) {
relatedUrls.add(tagMeta.externalDocs.url);
}
// Then aggregate from operations
operations.forEach((op) => {
// Check operation-level x-influxdatadocs-related (via opMeta.related)
if (op.related) {
op.related.forEach((url) => relatedUrls.add(url));
}
// Check operation-level externalDocs (legacy single link)
if (op.externalDocs?.url) {
relatedUrls.add(op.externalDocs.url);
}
@ -1185,6 +1218,14 @@ function writeOpenapiTagArticleData(
};
}
// Extract x-influxdatadocs-related if present
if (
operation['x-influxdatadocs-related'] &&
Array.isArray(operation['x-influxdatadocs-related'])
) {
opMeta.related = operation['x-influxdatadocs-related'];
}
operations.push(opMeta);
}
});

2
content/influxdb3/cloud-serverless/api/quick-start/_index.md
View File

@ -35,7 +35,7 @@ type: api
layout: single
staticFilePath: >-
/openapi/influxdb-cloud-serverless/ref/tags/influxdb-cloud-serverless-ref-quick-start.yaml
weight: 100
weight: 1
tag: Quick start
isConceptual: true
menuGroup: Concepts