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

fix(api): Fix RapiDoc operation filtering and improve API reference quality 

- Restore original RapiDoc match-paths format (method /path) for proper filtering
- Restrict operation tags to primary tag in tag-specific specs to prevent duplicates
- Rename Token tag to Auth token for clarity in Core and Enterprise specs
- Remove Table tag from cache operations (distinct_cache, last_cache)
- Add build script combining API docs, Hugo, and Markdown generation
- Skip summary rendering for conceptual pages
- Add isConceptual check to hide operations in nav for conceptual pages
claude/api-code-samples-plan-MEkQO
Jason Stirnaman 2025-12-12 10:52:50 -06:00
parent a1132142ff
commit 2fa00a36d2
16 changed files with 1470 additions and 1606 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
api-docs/influxdb3/core/v3/ref.yml
View File

@ -189,7 +189,7 @@ tags:
description: Retrieve server metrics, status, and version information
- name: Table
description: Manage table schemas and data
- name: Token
- name: Auth token
description: Manage tokens for authentication and authorization
- name: Write data
description: |
@ -1169,7 +1169,6 @@ paths:
description: Creates a distinct cache for a table.
tags:
- Cache data
- Table
requestBody:
required: true
content:
@ -1215,7 +1214,6 @@ paths:
description: Cache not found.
tags:
- Cache data
- Table
/api/v3/configure/last_cache:
post:
operationId: PostConfigureLastCache
@ -1240,7 +1238,6 @@ paths:
description: Cache already exists.
tags:
- Cache data
- Table
delete:
operationId: DeleteConfigureLastCache
summary: Delete last cache
@ -1270,7 +1267,6 @@ paths:
description: Cache not found.
tags:
- Cache data
- Table
/api/v3/configure/processing_engine_trigger:
post:
operationId: PostConfigureProcessingEngineTrigger
@ -1712,7 +1708,7 @@ paths:
$ref: '#/components/responses/Unauthorized'
tags:
- Authentication
- Token
- Auth token
/api/v3/configure/token/admin/regenerate:
post:
operationId: PostRegenerateAdminToken
@ -1731,7 +1727,7 @@ paths:
$ref: '#/components/responses/Unauthorized'
tags:
- Authentication
- Token
- Auth token
/api/v3/configure/token:
delete:
operationId: DeleteToken
@ -1755,7 +1751,7 @@ paths:
description: Token not found.
tags:
- Authentication
- Token
- Auth token
/api/v3/configure/token/named_admin:
post:
operationId: PostCreateNamedAdminToken
@ -1786,7 +1782,7 @@ paths:
description: A token with this name already exists.
tags:
- Authentication
- Token
- Auth token
/api/v3/plugins/files:
put:
operationId: PutPluginFile

16
api-docs/influxdb3/enterprise/v3/ref.yml
View File

@ -158,7 +158,7 @@ tags:
description: Retrieve server metrics, status, and version information
- name: Table
description: Manage table schemas and data
- name: Token
- name: Auth token
description: Manage tokens for authentication and authorization
- name: Write data
description: |
@ -1191,7 +1191,6 @@ paths:
description: Creates a distinct cache for a table.
tags:
- Cache data
- Table
requestBody:
required: true
content:
@ -1236,7 +1235,6 @@ paths:
description: Cache not found.
tags:
- Cache data
- Table
/api/v3/configure/last_cache:
post:
operationId: PostConfigureLastCache
@ -1261,7 +1259,6 @@ paths:
description: Cache already exists.
tags:
- Cache data
- Table
delete:
operationId: DeleteConfigureLastCache
summary: Delete last cache
@ -1291,7 +1288,6 @@ paths:
description: Cache not found.
tags:
- Cache data
- Table
/api/v3/configure/processing_engine_trigger:
post:
operationId: PostConfigureProcessingEngineTrigger
@ -1732,7 +1728,7 @@ paths:
$ref: '#/components/responses/Unauthorized'
tags:
- Authentication
- Token
- Auth token
/api/v3/configure/token/admin:
post:
operationId: PostCreateAdminToken
@ -1753,7 +1749,7 @@ paths:
$ref: '#/components/responses/Unauthorized'
tags:
- Authentication
- Token
- Auth token
/api/v3/configure/token/admin/regenerate:
post:
operationId: PostRegenerateAdminToken
@ -1772,7 +1768,7 @@ paths:
$ref: '#/components/responses/Unauthorized'
tags:
- Authentication
- Token
- Auth token
/api/v3/configure/token:
delete:
operationId: DeleteToken
@ -1795,7 +1791,7 @@ paths:
description: Token not found.
tags:
- Authentication
- Token
- Auth token
/api/v3/configure/token/named_admin:
post:
operationId: PostCreateNamedAdminToken
@ -1825,7 +1821,7 @@ paths:
description: A token with this name already exists.
tags:
- Authentication
- Token
- Auth token
/api/v3/plugins/files:
put:
operationId: PutPluginFile

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

File diff suppressed because it is too large Load Diff

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

File diff suppressed because it is too large Load Diff

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

@ -587,6 +587,7 @@ function generateOperationPages(options: GenerateOperationPagesOptions): void {
layout: 'operation',
// RapiDoc Mini configuration
specFile: tagSpecFile,
// RapiDoc match-paths format: "method /path" (e.g., "post /write")
matchPaths: `${method} ${op.path}`,
// Operation metadata
operationId: op.operationId,

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

@ -498,7 +498,11 @@ function writeTagOpenapis(
HTTP_METHODS.forEach((method) => {
const operation = pathItem[method] as Operation | undefined;
if (operation?.tags?.includes(tagName)) {
filteredPathItem[method] = operation;
// Clone the operation and restrict tags to only this tag
// This prevents RapiDoc from rendering the operation multiple times
// (once per tag) when an operation belongs to multiple tags
const filteredOperation = { ...operation, tags: [tagName] };
filteredPathItem[method] = filteredOperation;
hasOperations = true;
}
});

1
assets/js/components/rapidoc-mini.ts
View File

@ -166,6 +166,7 @@ function createRapiDocElement(
// Core attributes
element.setAttribute('spec-url', specUrl);
// matchPaths format: "method /path" (e.g., "post /write")
if (matchPaths) {
element.setAttribute('match-paths', matchPaths);
}

188
data/article_data/influxdb/influxdb3_core/articles.json
View File

@ -1,5 +1,63 @@
{
"articles": [
{
"path": "api/auth-token",
"fields": {
"name": "Auth token",
"describes": [
"/api/v3/configure/token/admin",
"/api/v3/configure/token/admin/regenerate",
"/api/v3/configure/token",
"/api/v3/configure/token/named_admin"
],
"title": "Auth token",
"description": "Manage tokens for authentication and authorization",
"tag": "Auth token",
"isConceptual": false,
"menuGroup": "Other",
"operations": [
{
"operationId": "PostCreateAdminToken",
"method": "POST",
"path": "/api/v3/configure/token/admin",
"summary": "Create admin token",
"tags": [
"Auth token"
]
},
{
"operationId": "PostRegenerateAdminToken",
"method": "POST",
"path": "/api/v3/configure/token/admin/regenerate",
"summary": "Regenerate admin token",
"tags": [
"Auth token"
]
},
{
"operationId": "DeleteToken",
"method": "DELETE",
"path": "/api/v3/configure/token",
"summary": "Delete token",
"tags": [
"Auth token"
]
},
{
"operationId": "PostCreateNamedAdminToken",
"method": "POST",
"path": "/api/v3/configure/token/named_admin",
"summary": "Create named admin token",
"tags": [
"Auth token"
]
}
],
"tagDescription": "Manage tokens for authentication and authorization",
"source": "static/openapi/influxdb3-core/tags/tags/ref-auth-token.yaml",
"staticFilePath": "/openapi/influxdb3-core/tags/tags/ref-auth-token.yaml"
}
},
{
"path": "api/authentication",
"fields": {
@ -22,8 +80,7 @@
"path": "/api/v3/configure/token/admin",
"summary": "Create admin token",
"tags": [
"Authentication",
"Token"
"Authentication"
]
},
{
@ -32,8 +89,7 @@
"path": "/api/v3/configure/token/admin/regenerate",
"summary": "Regenerate admin token",
"tags": [
"Authentication",
"Token"
"Authentication"
]
},
{
@ -42,8 +98,7 @@
"path": "/api/v3/configure/token",
"summary": "Delete token",
"tags": [
"Authentication",
"Token"
"Authentication"
]
},
{
@ -52,8 +107,7 @@
"path": "/api/v3/configure/token/named_admin",
"summary": "Create named admin token",
"tags": [
"Authentication",
"Token"
"Authentication"
]
}
],
@ -82,8 +136,7 @@
"path": "/api/v3/configure/distinct_cache",
"summary": "Create distinct cache",
"tags": [
"Cache data",
"Table"
"Cache data"
]
},
{
@ -92,8 +145,7 @@
"path": "/api/v3/configure/distinct_cache",
"summary": "Delete distinct cache",
"tags": [
"Cache data",
"Table"
"Cache data"
]
},
{
@ -102,8 +154,7 @@
"path": "/api/v3/configure/last_cache",
"summary": "Create last cache",
"tags": [
"Cache data",
"Table"
"Cache data"
]
},
{
@ -112,8 +163,7 @@
"path": "/api/v3/configure/last_cache",
"summary": "Delete last cache",
"tags": [
"Cache data",
"Table"
"Cache data"
]
}
],
@ -514,9 +564,7 @@
"fields": {
"name": "Table",
"describes": [
"/api/v3/configure/table",
"/api/v3/configure/distinct_cache",
"/api/v3/configure/last_cache"
"/api/v3/configure/table"
],
"title": "Table",
"description": "Manage table schemas and data",
@ -541,46 +589,6 @@
"tags": [
"Table"
]
},
{
"operationId": "PostConfigureDistinctCache",
"method": "POST",
"path": "/api/v3/configure/distinct_cache",
"summary": "Create distinct cache",
"tags": [
"Cache data",
"Table"
]
},
{
"operationId": "DeleteConfigureDistinctCache",
"method": "DELETE",
"path": "/api/v3/configure/distinct_cache",
"summary": "Delete distinct cache",
"tags": [
"Cache data",
"Table"
]
},
{
"operationId": "PostConfigureLastCache",
"method": "POST",
"path": "/api/v3/configure/last_cache",
"summary": "Create last cache",
"tags": [
"Cache data",
"Table"
]
},
{
"operationId": "DeleteConfigureLastCache",
"method": "DELETE",
"path": "/api/v3/configure/last_cache",
"summary": "Delete last cache",
"tags": [
"Cache data",
"Table"
]
}
],
"tagDescription": "Manage table schemas and data",
@ -588,68 +596,6 @@
"staticFilePath": "/openapi/influxdb3-core/tags/tags/ref-table.yaml"
}
},
{
"path": "api/token",
"fields": {
"name": "Token",
"describes": [
"/api/v3/configure/token/admin",
"/api/v3/configure/token/admin/regenerate",
"/api/v3/configure/token",
"/api/v3/configure/token/named_admin"
],
"title": "Token",
"description": "Manage tokens for authentication and authorization",
"tag": "Token",
"isConceptual": false,
"menuGroup": "Administration",
"operations": [
{
"operationId": "PostCreateAdminToken",
"method": "POST",
"path": "/api/v3/configure/token/admin",
"summary": "Create admin token",
"tags": [
"Authentication",
"Token"
]
},
{
"operationId": "PostRegenerateAdminToken",
"method": "POST",
"path": "/api/v3/configure/token/admin/regenerate",
"summary": "Regenerate admin token",
"tags": [
"Authentication",
"Token"
]
},
{
"operationId": "DeleteToken",
"method": "DELETE",
"path": "/api/v3/configure/token",
"summary": "Delete token",
"tags": [
"Authentication",
"Token"
]
},
{
"operationId": "PostCreateNamedAdminToken",
"method": "POST",
"path": "/api/v3/configure/token/named_admin",
"summary": "Create named admin token",
"tags": [
"Authentication",
"Token"
]
}
],
"tagDescription": "Manage tokens for authentication and authorization",
"source": "static/openapi/influxdb3-core/tags/tags/ref-token.yaml",
"staticFilePath": "/openapi/influxdb3-core/tags/tags/ref-token.yaml"
}
},
{
"path": "api/write-data",
"fields": {

124
data/article_data/influxdb/influxdb3_core/articles.yml
View File

@ -1,4 +1,45 @@
articles:
- path: api/auth-token
fields:
name: Auth token
describes:
- /api/v3/configure/token/admin
- /api/v3/configure/token/admin/regenerate
- /api/v3/configure/token
- /api/v3/configure/token/named_admin
title: Auth token
description: Manage tokens for authentication and authorization
tag: Auth token
isConceptual: false
menuGroup: Other
operations:
- operationId: PostCreateAdminToken
method: POST
path: /api/v3/configure/token/admin
summary: Create admin token
tags:
- Auth token
- operationId: PostRegenerateAdminToken
method: POST
path: /api/v3/configure/token/admin/regenerate
summary: Regenerate admin token
tags:
- Auth token
- operationId: DeleteToken
method: DELETE
path: /api/v3/configure/token
summary: Delete token
tags:
- Auth token
- operationId: PostCreateNamedAdminToken
method: POST
path: /api/v3/configure/token/named_admin
summary: Create named admin token
tags:
- Auth token
tagDescription: Manage tokens for authentication and authorization
source: static/openapi/influxdb3-core/tags/tags/ref-auth-token.yaml
staticFilePath: /openapi/influxdb3-core/tags/tags/ref-auth-token.yaml
- path: api/authentication
fields:
name: Authentication
@ -38,28 +79,24 @@ articles:
summary: Create admin token
tags:
- Authentication
- Token
- operationId: PostRegenerateAdminToken
method: POST
path: /api/v3/configure/token/admin/regenerate
summary: Regenerate admin token
tags:
- Authentication
- Token
- operationId: DeleteToken
method: DELETE
path: /api/v3/configure/token
summary: Delete token
tags:
- Authentication
- Token
- operationId: PostCreateNamedAdminToken
method: POST
path: /api/v3/configure/token/named_admin
summary: Create named admin token
tags:
- Authentication
- Token
tagDescription: >
Depending on your workflow, use one of the following schemes to
authenticate to the InfluxDB 3 API:
@ -162,28 +199,24 @@ articles:
summary: Create distinct cache
tags:
- Cache data
- Table
- operationId: DeleteConfigureDistinctCache
method: DELETE
path: /api/v3/configure/distinct_cache
summary: Delete distinct cache
tags:
- Cache data
- Table
- operationId: PostConfigureLastCache
method: POST
path: /api/v3/configure/last_cache
summary: Create last cache
tags:
- Cache data
- Table
- operationId: DeleteConfigureLastCache
method: DELETE
path: /api/v3/configure/last_cache
summary: Delete last cache
tags:
- Cache data
- Table
tagDescription: >
Manage the in-memory cache.
@ -817,8 +850,6 @@ articles:
name: Table
describes:
- /api/v3/configure/table
- /api/v3/configure/distinct_cache
- /api/v3/configure/last_cache
title: Table
description: Manage table schemas and data
tag: Table
@ -837,82 +868,9 @@ articles:
summary: Delete a table
tags:
- Table
- operationId: PostConfigureDistinctCache
method: POST
path: /api/v3/configure/distinct_cache
summary: Create distinct cache
tags:
- Cache data
- Table
- operationId: DeleteConfigureDistinctCache
method: DELETE
path: /api/v3/configure/distinct_cache
summary: Delete distinct cache
tags:
- Cache data
- Table
- operationId: PostConfigureLastCache
method: POST
path: /api/v3/configure/last_cache
summary: Create last cache
tags:
- Cache data
- Table
- operationId: DeleteConfigureLastCache
method: DELETE
path: /api/v3/configure/last_cache
summary: Delete last cache
tags:
- Cache data
- Table
tagDescription: Manage table schemas and data
source: static/openapi/influxdb3-core/tags/tags/ref-table.yaml
staticFilePath: /openapi/influxdb3-core/tags/tags/ref-table.yaml
- path: api/token
fields:
name: Token
describes:
- /api/v3/configure/token/admin
- /api/v3/configure/token/admin/regenerate
- /api/v3/configure/token
- /api/v3/configure/token/named_admin
title: Token
description: Manage tokens for authentication and authorization
tag: Token
isConceptual: false
menuGroup: Administration
operations:
- operationId: PostCreateAdminToken
method: POST
path: /api/v3/configure/token/admin
summary: Create admin token
tags:
- Authentication
- Token
- operationId: PostRegenerateAdminToken
method: POST
path: /api/v3/configure/token/admin/regenerate
summary: Regenerate admin token
tags:
- Authentication
- Token
- operationId: DeleteToken
method: DELETE
path: /api/v3/configure/token
summary: Delete token
tags:
- Authentication
- Token
- operationId: PostCreateNamedAdminToken
method: POST
path: /api/v3/configure/token/named_admin
summary: Create named admin token
tags:
- Authentication
- Token
tagDescription: Manage tokens for authentication and authorization
source: static/openapi/influxdb3-core/tags/tags/ref-token.yaml
staticFilePath: /openapi/influxdb3-core/tags/tags/ref-token.yaml
- path: api/write-data
fields:
name: Write data

212
data/article_data/influxdb/influxdb3_enterprise/articles.json
View File

@ -1,5 +1,73 @@
{
"articles": [
{
"path": "api/auth-token",
"fields": {
"name": "Auth token",
"describes": [
"/api/v3/configure/enterprise/token",
"/api/v3/configure/token/admin",
"/api/v3/configure/token/admin/regenerate",
"/api/v3/configure/token",
"/api/v3/configure/token/named_admin"
],
"title": "Auth token",
"description": "Manage tokens for authentication and authorization",
"tag": "Auth token",
"isConceptual": false,
"menuGroup": "Other",
"operations": [
{
"operationId": "PostCreateResourceToken",
"method": "POST",
"path": "/api/v3/configure/enterprise/token",
"summary": "Create a resource token",
"tags": [
"Auth token"
]
},
{
"operationId": "PostCreateAdminToken",
"method": "POST",
"path": "/api/v3/configure/token/admin",
"summary": "Create admin token",
"tags": [
"Auth token"
]
},
{
"operationId": "PostRegenerateAdminToken",
"method": "POST",
"path": "/api/v3/configure/token/admin/regenerate",
"summary": "Regenerate admin token",
"tags": [
"Auth token"
]
},
{
"operationId": "DeleteToken",
"method": "DELETE",
"path": "/api/v3/configure/token",
"summary": "Delete token",
"tags": [
"Auth token"
]
},
{
"operationId": "PostCreateNamedAdminToken",
"method": "POST",
"path": "/api/v3/configure/token/named_admin",
"summary": "Create named admin token",
"tags": [
"Auth token"
]
}
],
"tagDescription": "Manage tokens for authentication and authorization",
"source": "static/openapi/influxdb3-enterprise/tags/tags/ref-auth-token.yaml",
"staticFilePath": "/openapi/influxdb3-enterprise/tags/tags/ref-auth-token.yaml"
}
},
{
"path": "api/authentication",
"fields": {
@ -23,8 +91,7 @@
"path": "/api/v3/configure/enterprise/token",
"summary": "Create a resource token",
"tags": [
"Authentication",
"Token"
"Authentication"
]
},
{
@ -33,8 +100,7 @@
"path": "/api/v3/configure/token/admin",
"summary": "Create admin token",
"tags": [
"Authentication",
"Token"
"Authentication"
]
},
{
@ -43,8 +109,7 @@
"path": "/api/v3/configure/token/admin/regenerate",
"summary": "Regenerate admin token",
"tags": [
"Authentication",
"Token"
"Authentication"
]
},
{
@ -53,8 +118,7 @@
"path": "/api/v3/configure/token",
"summary": "Delete token",
"tags": [
"Authentication",
"Token"
"Authentication"
]
},
{
@ -63,8 +127,7 @@
"path": "/api/v3/configure/token/named_admin",
"summary": "Create named admin token",
"tags": [
"Authentication",
"Token"
"Authentication"
]
}
],
@ -93,8 +156,7 @@
"path": "/api/v3/configure/distinct_cache",
"summary": "Create distinct cache",
"tags": [
"Cache data",
"Table"
"Cache data"
]
},
{
@ -103,8 +165,7 @@
"path": "/api/v3/configure/distinct_cache",
"summary": "Delete distinct cache",
"tags": [
"Cache data",
"Table"
"Cache data"
]
},
{
@ -113,8 +174,7 @@
"path": "/api/v3/configure/last_cache",
"summary": "Create last cache",
"tags": [
"Cache data",
"Table"
"Cache data"
]
},
{
@ -123,8 +183,7 @@
"path": "/api/v3/configure/last_cache",
"summary": "Delete last cache",
"tags": [
"Cache data",
"Table"
"Cache data"
]
}
],
@ -545,9 +604,7 @@
"fields": {
"name": "Table",
"describes": [
"/api/v3/configure/table",
"/api/v3/configure/distinct_cache",
"/api/v3/configure/last_cache"
"/api/v3/configure/table"
],
"title": "Table",
"description": "Manage table schemas and data",
@ -581,46 +638,6 @@
"tags": [
"Table"
]
},
{
"operationId": "PostConfigureDistinctCache",
"method": "POST",
"path": "/api/v3/configure/distinct_cache",
"summary": "Create distinct cache",
"tags": [
"Cache data",
"Table"
]
},
{
"operationId": "DeleteConfigureDistinctCache",
"method": "DELETE",
"path": "/api/v3/configure/distinct_cache",
"summary": "Delete distinct cache",
"tags": [
"Cache data",
"Table"
]
},
{
"operationId": "PostConfigureLastCache",
"method": "POST",
"path": "/api/v3/configure/last_cache",
"summary": "Create last cache",
"tags": [
"Cache data",
"Table"
]
},
{
"operationId": "DeleteConfigureLastCache",
"method": "DELETE",
"path": "/api/v3/configure/last_cache",
"summary": "Delete last cache",
"tags": [
"Cache data",
"Table"
]
}
],
"tagDescription": "Manage table schemas and data",
@ -628,79 +645,6 @@
"staticFilePath": "/openapi/influxdb3-enterprise/tags/tags/ref-table.yaml"
}
},
{
"path": "api/token",
"fields": {
"name": "Token",
"describes": [
"/api/v3/configure/enterprise/token",
"/api/v3/configure/token/admin",
"/api/v3/configure/token/admin/regenerate",
"/api/v3/configure/token",
"/api/v3/configure/token/named_admin"
],
"title": "Token",
"description": "Manage tokens for authentication and authorization",
"tag": "Token",
"isConceptual": false,
"menuGroup": "Administration",
"operations": [
{
"operationId": "PostCreateResourceToken",
"method": "POST",
"path": "/api/v3/configure/enterprise/token",
"summary": "Create a resource token",
"tags": [
"Authentication",
"Token"
]
},
{
"operationId": "PostCreateAdminToken",
"method": "POST",
"path": "/api/v3/configure/token/admin",
"summary": "Create admin token",
"tags": [
"Authentication",
"Token"
]
},
{
"operationId": "PostRegenerateAdminToken",
"method": "POST",
"path": "/api/v3/configure/token/admin/regenerate",
"summary": "Regenerate admin token",
"tags": [
"Authentication",
"Token"
]
},
{
"operationId": "DeleteToken",
"method": "DELETE",
"path": "/api/v3/configure/token",
"summary": "Delete token",
"tags": [
"Authentication",
"Token"
]
},
{
"operationId": "PostCreateNamedAdminToken",
"method": "POST",
"path": "/api/v3/configure/token/named_admin",
"summary": "Create named admin token",
"tags": [
"Authentication",
"Token"
]
}
],
"tagDescription": "Manage tokens for authentication and authorization",
"source": "static/openapi/influxdb3-enterprise/tags/tags/ref-token.yaml",
"staticFilePath": "/openapi/influxdb3-enterprise/tags/tags/ref-token.yaml"
}
},
{
"path": "api/write-data",
"fields": {

140
data/article_data/influxdb/influxdb3_enterprise/articles.yml
View File

@ -1,4 +1,52 @@
articles:
- path: api/auth-token
fields:
name: Auth token
describes:
- /api/v3/configure/enterprise/token
- /api/v3/configure/token/admin
- /api/v3/configure/token/admin/regenerate
- /api/v3/configure/token
- /api/v3/configure/token/named_admin
title: Auth token
description: Manage tokens for authentication and authorization
tag: Auth token
isConceptual: false
menuGroup: Other
operations:
- operationId: PostCreateResourceToken
method: POST
path: /api/v3/configure/enterprise/token
summary: Create a resource token
tags:
- Auth token
- operationId: PostCreateAdminToken
method: POST
path: /api/v3/configure/token/admin
summary: Create admin token
tags:
- Auth token
- operationId: PostRegenerateAdminToken
method: POST
path: /api/v3/configure/token/admin/regenerate
summary: Regenerate admin token
tags:
- Auth token
- operationId: DeleteToken
method: DELETE
path: /api/v3/configure/token
summary: Delete token
tags:
- Auth token
- operationId: PostCreateNamedAdminToken
method: POST
path: /api/v3/configure/token/named_admin
summary: Create named admin token
tags:
- Auth token
tagDescription: Manage tokens for authentication and authorization
source: static/openapi/influxdb3-enterprise/tags/tags/ref-auth-token.yaml
staticFilePath: /openapi/influxdb3-enterprise/tags/tags/ref-auth-token.yaml
- path: api/authentication
fields:
name: Authentication
@ -37,35 +85,30 @@ articles:
summary: Create a resource token
tags:
- Authentication
- Token
- operationId: PostCreateAdminToken
method: POST
path: /api/v3/configure/token/admin
summary: Create admin token
tags:
- Authentication
- Token
- operationId: PostRegenerateAdminToken
method: POST
path: /api/v3/configure/token/admin/regenerate
summary: Regenerate admin token
tags:
- Authentication
- Token
- operationId: DeleteToken
method: DELETE
path: /api/v3/configure/token
summary: Delete token
tags:
- Authentication
- Token
- operationId: PostCreateNamedAdminToken
method: POST
path: /api/v3/configure/token/named_admin
summary: Create named admin token
tags:
- Authentication
- Token
tagDescription: >
Depending on your workflow, use one of the following schemes to
authenticate to the InfluxDB 3 API:
@ -159,28 +202,24 @@ articles:
summary: Create distinct cache
tags:
- Cache data
- Table
- operationId: DeleteConfigureDistinctCache
method: DELETE
path: /api/v3/configure/distinct_cache
summary: Delete distinct cache
tags:
- Cache data
- Table
- operationId: PostConfigureLastCache
method: POST
path: /api/v3/configure/last_cache
summary: Create last cache
tags:
- Cache data
- Table
- operationId: DeleteConfigureLastCache
method: DELETE
path: /api/v3/configure/last_cache
summary: Delete last cache
tags:
- Cache data
- Table
tagDescription: >
Manage the in-memory cache.
@ -787,8 +826,6 @@ articles:
name: Table
describes:
- /api/v3/configure/table
- /api/v3/configure/distinct_cache
- /api/v3/configure/last_cache
title: Table
description: Manage table schemas and data
tag: Table
@ -813,90 +850,9 @@ articles:
summary: Delete a table
tags:
- Table
- operationId: PostConfigureDistinctCache
method: POST
path: /api/v3/configure/distinct_cache
summary: Create distinct cache
tags:
- Cache data
- Table
- operationId: DeleteConfigureDistinctCache
method: DELETE
path: /api/v3/configure/distinct_cache
summary: Delete distinct cache
tags:
- Cache data
- Table
- operationId: PostConfigureLastCache
method: POST
path: /api/v3/configure/last_cache
summary: Create last cache
tags:
- Cache data
- Table
- operationId: DeleteConfigureLastCache
method: DELETE
path: /api/v3/configure/last_cache
summary: Delete last cache
tags:
- Cache data
- Table
tagDescription: Manage table schemas and data
source: static/openapi/influxdb3-enterprise/tags/tags/ref-table.yaml
staticFilePath: /openapi/influxdb3-enterprise/tags/tags/ref-table.yaml
- path: api/token
fields:
name: Token
describes:
- /api/v3/configure/enterprise/token
- /api/v3/configure/token/admin
- /api/v3/configure/token/admin/regenerate
- /api/v3/configure/token
- /api/v3/configure/token/named_admin
title: Token
description: Manage tokens for authentication and authorization
tag: Token
isConceptual: false
menuGroup: Administration
operations:
- operationId: PostCreateResourceToken
method: POST
path: /api/v3/configure/enterprise/token
summary: Create a resource token
tags:
- Authentication
- Token
- operationId: PostCreateAdminToken
method: POST
path: /api/v3/configure/token/admin
summary: Create admin token
tags:
- Authentication
- Token
- operationId: PostRegenerateAdminToken
method: POST
path: /api/v3/configure/token/admin/regenerate
summary: Regenerate admin token
tags:
- Authentication
- Token
- operationId: DeleteToken
method: DELETE
path: /api/v3/configure/token
summary: Delete token
tags:
- Authentication
- Token
- operationId: PostCreateNamedAdminToken
method: POST
path: /api/v3/configure/token/named_admin
summary: Create named admin token
tags:
- Authentication
- Token
tagDescription: Manage tokens for authentication and authorization
source: static/openapi/influxdb3-enterprise/tags/tags/ref-token.yaml
staticFilePath: /openapi/influxdb3-enterprise/tags/tags/ref-token.yaml
- path: api/write-data
fields:
name: Write data

171
docs/plans/2024-12-10-standalone-operation-pages-design.md Normal file
View File

@ -0,0 +1,171 @@
# Standalone API Operation Pages Design
## Overview
Create individual pages for each API operation with path-based URLs, rendered using RapiDoc Mini with existing tag-level OpenAPI specs.
## Goals
- **SEO/discoverability**: Each operation indexable with its own URL and metadata
- **Deep linking**: Reliable bookmarkable/shareable URLs for specific operations
- **Navigation UX**: Sidebar links navigate to actual pages (not hash fragments)
- **Content customization**: Foundation for adding operation-specific guides and examples
## URL Structure
Path-based URLs with HTTP method as the final segment:
| Operation | API Path | Page URL |
| ------------------ | ----------------------------------- | ------------------------------------ |
| PostV1Write | `POST /write` | `/api/write/post/` |
| PostV2Write | `POST /api/v2/write` | `/api/v2/write/post/` |
| PostWriteLP | `POST /api/v3/write_lp` | `/api/v3/write_lp/post/` |
| GetV1ExecuteQuery | `GET /query` | `/api/query/get/` |
| PostExecuteV1Query | `POST /query` | `/api/query/post/` |
| GetExecuteQuerySQL | `GET /api/v3/query_sql` | `/api/v3/query_sql/get/` |
| GetDatabases | `GET /api/v3/configure/database` | `/api/v3/configure/database/get/` |
| DeleteDatabase | `DELETE /api/v3/configure/database` | `/api/v3/configure/database/delete/` |
## Architecture
### Existing Components (unchanged)
- **Tag pages**: `/api/write-data/`, `/api/query-data/` etc. remain as landing pages
- **Tag-level specs**: `static/openapi/influxdb-{product}/tags/tags/ref-{tag}.yaml` (\~30-50KB each)
- **Sidebar structure**: Tag-based groups with operation summaries as link text
### New Components
1. **Operation page content files**: Generated at path-based locations
2. **Operation page template**: Hugo layout using RapiDoc Mini
3. **Updated sidebar links**: Point to path-based URLs instead of hash fragments
## Content File Structure
Generated operation pages at `content/influxdb3/{product}/api/{path}/{method}/_index.md`:
```yaml
---
title: Write line protocol (v1-compatible)
description: Write data using InfluxDB v1-compatible line protocol endpoint
type: api-operation
layout: operation
# RapiDoc Mini configuration
specFile: /openapi/influxdb-influxdb3_core/tags/tags/ref-write-data.yaml
matchPaths: post /write
# Operation metadata
operationId: PostV1Write
method: POST
apiPath: /write
tag: Write data
compatVersion: v1
# Links
related:
- /influxdb3/core/write-data/http-api/compatibility-apis/
---
```
## Hugo Template
New layout `layouts/api-operation/operation.html`:
```html
{{ define "main" }}
<article class="api-operation-page">
<header>
<h1>{{ .Title }}</h1>
<div class="api-operation-meta">
<span class="api-method api-method--{{ lower .Params.method }}">{{ .Params.method }}</span>
<code class="api-path">{{ .Params.apiPath }}</code>
{{ with .Params.compatVersion }}
<span class="api-compat-badge api-compat-badge--{{ . }}">{{ . }}</span>
{{ end }}
</div>
</header>
<rapi-doc-mini
spec-url="{{ .Params.specFile }}"
match-paths="{{ .Params.matchPaths }}"
theme="light"
bg-color="transparent"
paths-expanded="true"
schema-expand-level="1">
</rapi-doc-mini>
{{ with .Params.related }}
<aside class="related-content">
<h2>Related documentation</h2>
<ul>
{{ range . }}
<li><a href="{{ . }}">{{ . }}</a></li>
{{ end }}
</ul>
</aside>
{{ end }}
</article>
{{ end }}
```
## Sidebar Navigation Changes
Update `layouts/partials/sidebar/api-menu-items.html` to generate path-based URLs:
**Before:**
```go
{{ $fragment := printf "#operation/%s" .operationId }}
{{ $fullUrl := printf "%s%s" $tagPageUrl $fragment }}
```
**After:**
```go
{{ $apiPath := .path }}
{{ $method := lower .method }}
{{ $pathSlug := $apiPath | replaceRE "^/" "" }}
{{ $operationUrl := printf "/%s/%s/api/%s/%s/" $product $version $pathSlug $method | relURL }}
```
## Generator Changes
Update `api-docs/scripts/openapi-paths-to-hugo-data/index.ts`:
1. Add new function `generateOperationPages()` that creates content files for each operation
2. Include operation metadata: specFile path, matchPaths filter, tag association
3. Call from `generateHugoDataByTag()` after generating tag-based articles
## File Generation Summary
For InfluxDB 3 Core (\~43 operations), this creates:
- \~43 new content files at `content/influxdb3/core/api/{path}/{method}/_index.md`
- No new spec files (reuses existing tag-level specs)
## Data Flow
```
OpenAPI Spec
↓
Generator extracts operations
↓
Creates content files with frontmatter (specFile, matchPaths, metadata)
↓
Hugo builds pages using api-operation/operation.html template
↓
RapiDoc Mini loads tag-level spec, filters to single operation client-side
```
## Testing Plan
1. Generate operation pages for Core product
2. Verify URLs resolve correctly
3. Verify RapiDoc Mini renders single operation
4. Verify sidebar links navigate to operation pages
5. Test deep linking (direct URL access)
6. Check page titles and meta descriptions for SEO
## Future Improvements
- Generate operation-level specs for smaller payloads (if performance issues arise)
- Add custom content sections per operation
- Implement operation search/filtering on tag pages

12
layouts/api/single.html
View File

@ -46,12 +46,14 @@
<h1 class="article--title">{{ .Title }}</h1>
{{ end }}
{{/* Summary/Description */}}
{{ with .Params.summary }}
<p class="article--summary">{{ . | markdownify }}</p>
{{ else }}
{{ with .Description }}
{{/* Summary/Description - skip for conceptual pages (shown in content section) */}}
{{ if not (.Params.isConceptual | default false) }}
{{ with .Params.summary }}
<p class="article--summary">{{ . | markdownify }}</p>
{{ else }}
{{ with .Description }}
<p class="article--summary">{{ . | markdownify }}</p>
{{ end }}
{{ end }}
{{ end }}
</div>

3
layouts/partials/api/rapidoc-mini.html
View File

@ -95,8 +95,9 @@ rapi-doc::part(section-tag) {
}
/* Fix parameter table layout - reduce indentation from empty td cells */
/* Match site's body font size (16px) for consistency */
rapi-doc {
--font-size-regular: 14px;
--font-size-regular: 16px;
}
/* Fix auth schemes at narrow widths - ensure content is scrollable */

14
layouts/partials/sidebar/api-menu-items.html
View File

@ -133,7 +133,12 @@
{{ if and (reflect.IsMap $fields) (isset $fields "operations") }}
{{ $operations = index $fields "operations" }}
{{ end }}
{{ $hasOperations := gt (len $operations) 0 }}
{{/* Don't show operations for conceptual/traitTag pages (e.g., Authentication) */}}
{{ $isConceptual := false }}
{{ if and (reflect.IsMap $fields) (isset $fields "isConceptual") }}
{{ $isConceptual = index $fields "isConceptual" }}
{{ end }}
{{ $hasOperations := and (gt (len $operations) 0) (not $isConceptual) }}
<li class="nav-item{{ if $isActive }} active{{ end }}">
{{ if $hasOperations }}<a href="#" class="children-toggle{{ if or $isActive $groupIsOpen }} open{{ end }}"></a>{{ end }}
@ -195,7 +200,12 @@
{{ if and (reflect.IsMap $fields) (isset $fields "menuName") }}
{{ $menuName = index $fields "menuName" }}
{{ end }}
{{ $hasOperations := gt (len $operations) 0 }}
{{/* Don't show operations for conceptual/traitTag pages (e.g., Authentication) */}}
{{ $isConceptual := false }}
{{ if and (reflect.IsMap $fields) (isset $fields "isConceptual") }}
{{ $isConceptual = index $fields "isConceptual" }}
{{ end }}
{{ $hasOperations := and (gt (len $operations) 0) (not $isConceptual) }}
<li class="nav-item{{ if $isActive }} active{{ end }}">
{{ if $hasOperations }}<a href="#" class="children-toggle{{ if $isActive }} open{{ end }}"></a>{{ end }}

1
package.json
View File

@ -58,6 +58,7 @@
"vanillajs-datepicker": "^1.3.4"
},
"scripts": {
"build": "yarn build:api-docs && npx hugo --quiet && yarn build:md",
"postinstall": "node scripts/setup-local-bin.js",
"docs:create": "node scripts/docs-create.js",
"docs:edit": "node scripts/docs-edit.js",