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

chore/api-tags flatten tags (#4191) 

* chore(api):

- Replace some x-tagGroups with tags to flatten the navigation and redundant headings.
- Remove unnecessary x-tagGroups from 1.x compat docs.

* chore: remove unused tag-group files.

* chore: update api-docs README

- Document the generate -c flag.
- Cleanup.

Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com>
pull/4206/head
Jason Stirnaman 2022-07-12 12:21:35 -05:00 committed by GitHub
parent 836bd1bcbd
commit 064d9d0a25
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 138 additions and 123 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

87
api-docs/README.md
View File

@ -20,14 +20,8 @@
sh getswagger.sh cloud
```
3. Enter the following commands into your terminal to generate the API docs with Redocly:
```sh
sh generate-api-docs.sh
```
To troubleshoot errors, see [how to generate API docs locally](#how-to-generate-api-docs-locally).
4. Commit the changes, push your branch to `influxdata/docs-v2`, and create a PR against the `master` branch.
3. To generate the HTML files for local testing, follow the instructions to [generate API docs locally](#generate-api-docs-locally).
4. To commit your updated spec files, push your branch to `influxdata/docs-v2`, and create a PR against the `master` branch.
## Update API docs for an InfluxDB OSS release
@ -47,6 +41,8 @@
```sh
git tag influxdb-oss-v[SEMANTIC_VERSION] COMMIT_SHA
```
4. Enter the following commands into your terminal to push the new tag to the repo:
```sh
@ -59,6 +55,8 @@
git checkout docs-release/influxdb-oss
git rebase -i OSS_RELEASE_TAG
git push -f origin docs-release/influxdb-oss
```
6. Go into your `docs-v2` directory and create a branch for your changes--for example:
```sh
@ -84,15 +82,8 @@
sh getswagger.sh oss
```
To troubleshoot errors, see [how to generate API docs locally](#how-to-generate-api-docs-locally).
9. Enter the following commands into your terminal to generate the API docs with Redocly:
```sh
sh generate-api-docs.sh
```
To troubleshoot errors, see [how to generate API docs locally](#how-to-generate-api-docs-locally).
10. Commit the changes, push your branch to `influxdata/docs-v2`, and create a PR against the `master` branch.
9. To generate the HTML files for local testing, follow the instructions to [generate API docs locally](#generate-api-docs-locally).
10. To commit your updated spec files, push your branch to `influxdata/docs-v2`, and create a PR against the `master` branch.
## Update API docs for OSS spec changes between releases
@ -139,13 +130,8 @@ Follow these steps to update OSS API docs between version releases--for example,
sh getswagger.sh oss
```
7. Enter the following commands into your terminal to generate the API docs with Redocly:
```sh
sh generate-api-docs.sh
```
8. Commit the changes, push your branch to `influxdata/docs-v2`, and create a PR against the `master` branch.
7. To generate the HTML files for local testing, follow the instructions to [generate API docs locally](#generate-api-docs-locally).
8. To commit your updated spec files, push your branch to `influxdata/docs-v2`, and create a PR against the `master` branch.
## Generate InfluxDB API docs
@ -159,6 +145,37 @@ not committed to the docs repo.
The InfluxDB docs deployment process uses OpenAPI specification files in the `api-docs` directory
to generate version-specific (Cloud, OSS v2.1, OSS v2.0, etc.) API documentation.
### Generate API docs locally
Because the API documentation HTML is gitignored, you must manually generate it
to view the API docs locally.
The `./generate.sh` script uses the Redoc CLI to generate Redocly HTML, Javascript,
and CSS for each version of the InfluxDB spec.
The script uses `npx` to download and execute the Redocly CLI.
1. Verify that you have a working `npx` (it's included with Node.js).
In your terminal, run:
```sh
npx --version
```
If `npx` returns errors, [download](https://nodejs.org/en/) and run a recent version of the Node.js installer for your OS.
2. To generate API docs for _all_ InfluxDB versions in `./openapi`, enter the following command into your terminal:
```sh
sh generate-api-docs.sh
```
To save time testing your spec changes, you can pass the `-c` flag
to regenerate HTML for only the OpenAPI files that differ from your `master` branch.
```sh
sh generate-api-docs.sh -c
```
## How we version OpenAPI contracts
The `api-docs` directory structure versions OpenAPI files using the following pattern:
@ -202,28 +219,6 @@ for the `influxdata/openapi` commit used in OSS v2.2.0, see https://github.com/i
For convenience, we tag `influxdata/influxdb` (OSS) release points in `influxdata/openapi` as
`influxdb-oss-v[OSS_VERSION]`. See <https://github.com/influxdata/openapi/tags>.
## How to generate API docs locally
Because the API documentation HTML is gitignored, you must manually generate it
to view the API docs locally.
Verify that you have a working `npx` (it's included with Node.js).
In your terminal, run:
```sh
npx --version
```
If `npx` returns errors, [download](https://nodejs.org/en/) and run a recent version of the Node.js installer for your OS.
```sh
# In your terminal, go to the `docs-v2/api-docs` directory:
cd api-docs
# Generate the API docs with Redocly
sh generate-api-docs.sh
```
## How to use custom OpenAPI spec processing
Generally, you should manage API content in `influxdata/openapi`.

124
api-docs/cloud/ref.yml
View File

@ -6203,6 +6203,7 @@ paths:
summary: List all top level routes
tags:
- Routes
- System information endpoints
/api/v2/authorizations:
get:
operationId: GetAuthorizations
@ -8506,7 +8507,21 @@ paths:
$ref: '#/components/responses/GeneralServerError'
summary: Delete data
tags:
- Data I/O endpoints
- Delete
x-codeSamples:
- label: cURL
lang: Shell
source: >
curl --request POST
INFLUX_URL/api/v2/delete?org=INFLUX_ORG&bucket=INFLUX_BUCKET \
--header 'Authorization: Token INFLUX_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"start": "2020-03-01T00:00:00Z",
"stop": "2020-11-14T00:00:00Z",
"predicate": "tag1=\"value1\" and (tag2=\"value2\" and tag3!=\"value3\")"
}'
/api/v2/flags:
get:
operationId: GetFlags
@ -9385,6 +9400,7 @@ paths:
summary: List all organizations
tags:
- Organizations
- Security and access endpoints
post:
operationId: PostOrgs
parameters:
@ -9467,6 +9483,7 @@ paths:
summary: Retrieve an organization
tags:
- Organizations
- Security and access endpoints
patch:
operationId: PatchOrgsID
parameters:
@ -9562,6 +9579,7 @@ paths:
summary: List all members of an organization
tags:
- Organizations
- Security and access endpoints
post:
operationId: PostOrgsIDMembers
parameters:
@ -9624,6 +9642,7 @@ paths:
summary: Remove a member from an organization
tags:
- Organizations
- Security and access endpoints
/api/v2/orgs/{orgID}/owners:
get:
operationId: GetOrgsIDOwners
@ -9657,6 +9676,7 @@ paths:
summary: List all owners of an organization
tags:
- Organizations
- Security and access endpoints
post:
operationId: PostOrgsIDOwners
parameters:
@ -9719,6 +9739,7 @@ paths:
summary: Remove an owner from an organization
tags:
- Organizations
- Security and access endpoints
/api/v2/orgs/{orgID}/secrets:
get:
operationId: GetOrgsIDSecrets
@ -9746,6 +9767,7 @@ paths:
summary: List all secret keys for an organization
tags:
- Secrets
- Security and access endpoints
patch:
operationId: PatchOrgsIDSecrets
parameters:
@ -9801,6 +9823,7 @@ paths:
summary: Delete a secret from an organization
tags:
- Secrets
- Security and access endpoints
/api/v2/orgs/{orgID}/secrets/delete:
post:
deprecated: true
@ -9832,6 +9855,7 @@ paths:
summary: Delete secrets from an organization
tags:
- Secrets
- Security and access endpoints
/api/v2/orgs/{orgID}/usage:
get:
operationId: GetOrgUsageID
@ -9927,6 +9951,7 @@ paths:
summary: Get the status and version of the instance
tags:
- Ping
- System information endpoints
head:
description: Returns the status and InfluxDB version of the instance.
operationId: HeadPing
@ -9954,7 +9979,7 @@ paths:
Retrieves data from buckets.
Use this endpoint to send a Flux query request and retreive data from a
Use this endpoint to send a Flux query request and retrieve data from a
bucket.
@ -10057,13 +10082,16 @@ paths:
responses:
'200':
content:
text/csv:
application/csv:
example: >
result,table,_start,_stop,_time,region,host,_value
mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43
mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25
mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62
schema:
example: >
result,table,_start,_stop,_time,region,host,_value
mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43
mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25
mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62
type: string
description: Success. The response body contains query results.
headers:
@ -10116,7 +10144,19 @@ paths:
$ref: '#/components/responses/GeneralServerError'
summary: Query data
tags:
- Data I/O endpoints
- Query
x-codeSamples:
- label: cURL
lang: Shell
source: |
curl --request POST 'INFLUX_URL/api/v2/query?org=INFLUX_ORG' \
--header 'Content-Type: application/vnd.flux' \
--header 'Accept: application/csv \
--header 'Authorization: Token INFLUX_TOKEN' \
--data 'from(bucket: "example-bucket")
|> range(start: -5m)
|> filter(fn: (r) => r._measurement == "example-measurement")'
/api/v2/query/analyze:
post:
operationId: PostQueryAnalyze
@ -10264,6 +10304,7 @@ paths:
summary: List all known resources
tags:
- Resources
- System information endpoints
/api/v2/scripts:
get:
operationId: GetScripts
@ -10292,6 +10333,7 @@ paths:
description: Unexpected error
summary: List scripts
tags:
- Data I/O endpoints
- Invokable Scripts
post:
operationId: PostScripts
@ -10357,6 +10399,7 @@ paths:
description: Unexpected error
summary: Retrieve a script
tags:
- Data I/O endpoints
- Invokable Scripts
patch:
description: >
@ -10419,6 +10462,7 @@ paths:
description: Unexpected error
summary: Invoke a script
tags:
- Data I/O endpoints
- Invokable Scripts
/api/v2/setup:
get:
@ -10852,6 +10896,7 @@ paths:
description: Unexpected error
summary: List all tasks
tags:
- Data I/O endpoints
- Tasks
post:
operationId: PostTasks
@ -10879,6 +10924,7 @@ paths:
description: Unexpected error
summary: Create a new task
tags:
- Data I/O endpoints
- Tasks
/api/v2/tasks/{taskID}:
delete:
@ -10929,6 +10975,7 @@ paths:
description: Unexpected error
summary: Retrieve a task
tags:
- Data I/O endpoints
- Tasks
patch:
description: Update a task. This will cancel all queued runs.
@ -11345,6 +11392,7 @@ paths:
description: Unexpected error
summary: Manually start a task run, overriding the current schedule
tags:
- Data I/O endpoints
- Tasks
/api/v2/tasks/{taskID}/runs/{runID}:
delete:
@ -12197,6 +12245,7 @@ paths:
- BasicAuthentication: []
summary: Update a password
tags:
- Security and access endpoints
- Users
/api/v2/variables:
get:
@ -12783,11 +12832,13 @@ paths:
#### InfluxDB Cloud
- Returns this error if a **read** or **write** request exceeds your
plan's [adjustable service quotas](/influxdb/cloud/account-management/limits/#adjustable-service-quotas)
or if a **delete** request exceeds the maximum
[global limit](/influxdb/cloud/account-management/limits/#global-limits).
- Returns `Retry-After` header that describes when to try the write again.
- Returns this error if a **read** or **write** request exceeds your plan's [adjustable service quotas](/influxdb/cloud/account-management/limits/#adjustable-service-quotas)
or if a **delete** request exceeds the maximum [global limit](/influxdb/cloud/account-management/limits/#global-limits).
- For rate limits that reset automatically, returns a `Retry-After` header that describes when to try the write again.
- For limits that can't reset (for example, **cardinality limit**), doesn't return a `Retry-After` header.
Rates (data-in (writes), queries (reads), and deletes) accrue within a fixed five-minute window.
Once a rate limit is exceeded, InfluxDB returns an error response until the current five-minute window resets.
#### InfluxDB OSS
@ -12803,20 +12854,14 @@ paths:
'500':
$ref: '#/components/responses/InternalServerError'
'503':
description: |
description: >
Service unavailable.
#### InfluxDB Cloud
- Returns this error if series cardinality exceeds your plan's
[adjustable service quotas](/influxdb/cloud/account-management/limits/#adjustable-service-quotas).
See [how to resolve high series cardinality](/influxdb/cloud/write-data/best-practices/resolve-high-cardinality/).
#### InfluxDB OSS
- Returns this error if
the server is temporarily unavailable to accept writes.
- Returns `Retry-After` header that describes when to try the write again.
- Returns this error if
the server is temporarily unavailable to accept writes.
- Returns a `Retry-After` header that describes when to try the
write again.
headers:
Retry-After:
description: >-
@ -12829,6 +12874,7 @@ paths:
$ref: '#/components/responses/GeneralServerError'
summary: Write data
tags:
- Data I/O endpoints
- Write
/legacy/authorizations:
get:
@ -13379,8 +13425,11 @@ tags:
name: Common parameters
x-traitTag: true
- name: Dashboards
- name: Data I/O endpoints
- name: DBRPs
- name: Delete
- description: |
Delete data from an InfluxDB bucket.
name: Delete
- description: >
InfluxDB API endpoints use standard HTTP request and response headers.
@ -13523,9 +13572,11 @@ tags:
- name: Routes
- name: Rules
- name: Secrets
- name: Security and access endpoints
- name: Setup
- name: Signin
- name: Signout
- name: System information endpoints
- name: Tasks
- name: Telegraf Plugins
- name: Telegrafs
@ -13544,28 +13595,11 @@ x-tagGroups:
- Authentication
- Headers
- Response codes
- name: Data I/O endpoints
- name: ''
tags:
- Write
- Query
- Delete
- Invokable Scripts
- Tasks
- name: Resource endpoints
tags:
- Buckets
- Dashboards
- Tasks
- Resources
- name: Security and access endpoints
tags:
- Authorizations
- Organizations
- Users
- name: System information endpoints
tags:
- Ping
- Routes
- Data I/O endpoints
- Security and access endpoints
- System information endpoints
- name: All endpoints
tags:
- Authorizations

13
api-docs/cloud/swaggerV1Compat.yml
View File

@ -509,15 +509,4 @@ tags:
x-traitTag: true
- name: Query
- name: Write
x-tagGroups:
- name: Overview
tags:
- Authentication
- name: Data I/O endpoints
tags:
- Write
- Query
- name: All endpoints
tags:
- Query
- Write
x-tagGroups: []

9
api-docs/openapi/content/cloud/v1compat/tag-groups.yml
View File

@ -1,9 +0,0 @@
- name: Overview
tags:
- Authentication
- name: Data I/O endpoints
tags:
- Write
- Query
- name: All endpoints
tags: []

9
api-docs/openapi/content/v2.3/v1compat/tag-groups.yml
View File

@ -1,9 +0,0 @@
- name: Overview
tags:
- Authentication
- name: Data I/O endpoints
tags:
- Write
- Query
- name: All endpoints
tags: []

19
api-docs/openapi/plugins/decorators/tags/set-tag-groups.js
View File

@ -50,11 +50,26 @@ function SetTagGroups() {
root['x-tagGroups'] = data;
}
let nonEndpointTags = []
root['x-tagGroups'].map(
function(grp) {
grp.tags = grp.name === 'All endpoints' ? endpointTags : grp.tags;
return grp;
if(grp.name !== 'All endpoints') {
nonEndpointTags = nonEndpointTags.concat(grp.tags);
}
if(!['All endpoints', 'Overview'].includes(grp.name)) {
grp.name = ""
}
});
root['x-tagGroups'].map(
function(grp) {
if(grp.name === 'All endpoints') {
grp.tags = endpointTags
.filter(t => !nonEndpointTags.includes(t));
}
return grp;
}
)
}
}
}