Merge pull request #500 from influxdata/api/auto-gen

Auto-generated API docs and other fixes
2019-09-30 11:26:49 -06:00 · 2019-09-30 11:26:49 -06:00 · 57e352724c
parent 012a629fc2 678b0a9bf1
commit 57e352724c
13 changed files with 10302 additions and 14 deletions
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@ -23,7 +23,10 @@ jobs:
          command: ./deploy/ci-install-s3deploy.sh
      - run:
          name: Install NPM dependencies
-          command: sudo npm i -g postcss-cli autoprefixer
+          command: sudo npm i -g postcss-cli autoprefixer redoc-cli
+      - run:
+          name: Generate API documentation
+          command: cd api-docs && bash generate-api-docs.sh
      - save_cache:
          key: install-v1-{{ checksum ".circleci/config.yml" }}
          paths:
--- a/.gitignore
+++ b/.gitignore
@ -5,3 +5,4 @@ public
 node_modules
 *.log
 /resources
+/content/**/api.html
--- a/api-docs/README.md
+++ b/api-docs/README.md
@ -0,0 +1,37 @@
+## Generate InfluxDB API docs
+InfluxDB uses [Redoc](https://github.com/Redocly/redoc/) and
+[redoc-cli](https://github.com/Redocly/redoc/blob/master/cli/README.md) to generate
+API documentation from the InfluxDB `swagger.yml`.
+
+To minimize repo size, the generated API documentation HTML is gitignored, therefore
+not committed directly to the docs repo.
+The InfluxDB docs deployment process uses swagger files in the `api-docs` directory
+to generate version-specific API documentation.
+
+### Versioned swagger files
+Structure versions swagger files using the following pattern:
+
+```
+api-docs/
+  ├── v2.0/
+  │     └── swagger.yml
+  ├── v2.1/
+  │     └── swagger.yml
+  ├── v2.2/
+  │     └── swagger.yml
+  └── etc...
+```
+
+### Generate API docs locally
+Because the API documentation HTML is gitignored, you must manually generate it
+to view the API docs locally.
+
+From the root of the docs repo, run:
+
+```sh
+# Install redoc-cli
+npm install -g redoc-cli
+
+# Generate the API docs
+cd api-docs && generate-api-docs.sh
+```
--- a/api-docs/generate-api-docs.sh
+++ b/api-docs/generate-api-docs.sh
@ -0,0 +1,42 @@
+#!/bin/bash -e
+
+# Get list of versions from directory names
+versions="$(ls -d -- */)"
+
+for version in $versions
+do
+  # Trim the trailing slash off the directory name
+  version="${version%/}"
+  menu="${version//./_}_ref"
+
+  # Generate the frontmatter
+  frontmatter="---
+title: InfluxDB $version API documentation
+description: >
+  The InfluxDB API provides a programmatic interface for interactions with InfluxDB $version.
+layout: api
+menu:
+  $menu:
+    parent: InfluxDB v2 API
+    name: View full API docs
+weight: 102
+---
+"
+
+  # Use Redoc to generate the API html
+  redoc-cli bundle -t template.hbs \
+    --title="InfluxDB $version API documentation" \
+    --options.sortPropsAlphabetically \
+    --options.menuToggle \
+    --options.hideHostname \
+    --templateOptions.version="$version" \
+    $version/swagger.yml
+
+  # Create temp file with frontmatter and Redoc html
+  echo "$frontmatter" >> $version.tmp
+  cat redoc-static.html >> $version.tmp
+
+  # Remove redoc file and move the tmp file to it's proper place
+  rm -f redoc-static.html
+  mv $version.tmp ../content/$version/api.html
+done
--- a/api-docs/template.hbs
+++ b/api-docs/template.hbs
@ -0,0 +1,52 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+  <meta charset="utf8" />
+  <title>{{title}}</title>
+  <meta name="description" content="The InfluxDB API provides a programmatic interface for interactions with InfluxDB {{templateOptions.version}}.">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="shortcut icon" href="/img/favicon.png" type="image/png" sizes="32x32">
+
+  <script async src="https://www.googletagmanager.com/gtag/js?id=UA-45024174-12"></script>
+  <script>
+    window.dataLayer = window.dataLayer || [];
+    function gtag(){dataLayer.push(arguments);}
+    gtag('js', new Date());
+    gtag('config', 'UA-45024174-12');
+  </script>
+  <meta name="google-site-verification" content="_V6CNhaIIgVsTO9max_ECw7DUfPL-ZGE7G03MQgEGMU" />
+
+  <style>
+    body {
+      padding: 0;
+      margin: 0;
+    }
+  </style>
+  {{#unless disableGoogleFont}}<link href="https://fonts.googleapis.com/css?family=Roboto+Mono:500,500i,700,700i|Roboto:400,400i,700,700i|Rubik:400,400i,500,500i,700,700i" rel="stylesheet">{{/unless}}
+  {{{redocHead}}}
+  <link rel="stylesheet" type="text/css" href="/api.css">
+</head>
+
+<body>
+  <div id="loading">
+    <div class="spinner"></div>
+  </div>
+  <div id="influx-header">
+    <a href="/{{templateOptions.version}}">InfluxDB {{templateOptions.version}} Docs</a>
+  </div>
+  {{{redocHTML}}}
+  <script type="text/javascript">
+    function removeFadeOut( el, speed ) {
+      var seconds = speed/1000;
+      el.style.transition = "opacity "+seconds+"s ease";
+      el.style.opacity = 0;
+      setTimeout(function() {
+          el.parentNode.removeChild(el);
+      }, speed);
+    }
+    removeFadeOut(document.getElementById('loading'), 500);
+  </script>
+</body>
+
+</html>
--- a/api-docs/v2.0/swagger.yml
+++ b/api-docs/v2.0/swagger.yml
--- a/assets/styles/layouts/_api-overrides.scss
+++ b/assets/styles/layouts/_api-overrides.scss
@ -0,0 +1,266 @@
+@import "tools/color-palette";
+@import "tools/icomoon";
+
+// Fonts
+$rubik: 'Rubik', sans-serif;
+$roboto: 'Roboto', sans-serif;
+$roboto-mono: 'Roboto Mono', monospace;
+
+// Font weights
+$medium: 500;
+$bold: 700;
+
+//////////////////////////////////// LOADER ////////////////////////////////////
+
+#loading {
+  position: fixed;
+  width: 100vw;
+  height: 100vh;
+  z-index: 1000;
+  background-color: $g20-white;
+  opacity: 1;
+  transition: opacity .5s;
+}
+
+@keyframes spinner {
+  to {transform: rotate(360deg);}
+}
+
+.spinner:before {
+  content: '';
+  box-sizing: border-box;
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 50px;
+  height: 50px;
+  margin-top: -25px;
+  margin-left: -25px;
+  border-radius: 50%;
+  border: 3px solid $g16-pearl;
+  border-top-color: $cp-comet;
+  animation: spinner .6s linear infinite;
+}
+
+//////////////////////////////// InfluxDB Header ///////////////////////////////
+
+#influx-header {
+  font-family: $rubik;
+  padding: 15px 20px ;
+  display: block;
+  background-color: $wp-violentdark;
+  a {
+    color: $g20-white;
+    text-decoration: none;
+    transition: color .2s;
+    &:hover {
+      color: $b-pool;
+    }
+    &:before {
+      content: '\e918';
+      font-family: 'icomoon';
+      margin-right: .65rem;
+    }
+  }
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+.cjtbAK {
+  h1,h2,h3,h4,h5,h6,
+  p,li,th,td {
+    font-family: $rubik !important;
+  }
+}
+
+#redoc {
+  h1,h2,h3,h4,h5,h6 {
+    font-weight: $medium !important;
+  }
+}
+
+// Section title padding
+.dluJDj {
+  padding: 20px 0;
+}
+
+// Page h1
+.dTJWQH {
+  color: $g7-graphite;
+  font-size: 2rem;
+}
+
+// Download button
+.jIdpVJ {
+  background: $b-dodger;
+  color: $g20-white;
+  border: none;
+  border-radius: 3px;
+  font-family: $rubik;
+  font-size: .85rem;
+  font-weight: $medium;
+  transition: background-color .2s;
+  &:hover {
+    background-color: $b-pool;
+  }
+}
+
+// Tag h1s
+.WxWXp {
+  color: $g7-graphite;
+  font-size: 1.75rem;
+}
+
+// Summaru h2s and table headers
+.ioYTqA, .bxcHYI, .hoUoen {
+  color: $g7-graphite;
+}
+
+// h3s
+.espozG {
+  color: $g8-storm;
+}
+
+// Links
+.bnFPhO a { color: $b-dodger;
+  &:visited {color: $b-dodger;}
+}
+
+.redoc-json {
+  font-family: $roboto-mono !important;
+}
+
+// Inline Code
+.flfxUM code,
+.gDsWLk code,
+.kTVySD {
+  font-family: $roboto-mono !important;
+  color: $cp-marguerite;
+  background: $cp-titan;
+  border-color: $cp-titan;
+}
+
+// Required tags
+.jsTAxL {
+  color: $o-curacao;
+}
+
+///////////////////////////// RESPONSE COLOR BLOCKS ////////////////////////////
+
+// Green
+.hLVzSF {
+  background-color: rgba($gr-wasabi, .5);
+  color: $gr-emerald;
+}
+
+// Red
+.byLrBg {
+  background-color: rgba($o-marmelade, .35);
+  color: $o-curacao;
+}
+
+
+
+/////////////////////////////////// LEFT NAV ///////////////////////////////////
+
+// Left nav background
+.gZdDsM {
+  background-color: $g19-ghost;
+}
+
+.gpbcFk:hover, .sc-eTuwsz.active {
+  background-color: rgb(237, 237, 237);
+}
+
+// List item text
+.SmuWE, .gcUzvG, .bbViyS, .sc-hrWEMg label {
+  font-family: $rubik !important;
+}
+
+.fyUykq {
+  font-weight: $medium;
+}
+
+// Request method tags
+.cFwMcp {
+  &.post { background-color: $b-curious; }
+  &.get { background-color: $gr-canopy; }
+  &.put { background-color: $cp-comet; }
+  &.patch { background-color: $ch-keylime; }
+  &.delete { background-color: $o-curacao; }
+}
+
+// Active nav section
+.gcUzvG, .iNzLCk:hover {
+  color: $m-magenta;
+}
+
+/////////////////////////////// RIGHT CODE COLUMN //////////////////////////////
+
+// Right column backgrounds
+.dtUibw, .fLUKgj {
+  background-color: $wp-jagger;
+  h3,h4,h5,h6 {
+    font-family: $rubik !important;
+    font-weight: $medium !important;
+  }
+}
+
+// Code backgrounds
+.irpqyy > .react-tabs__tab-panel {
+  background-color: $wp-telopea;
+}
+.dHLKeu, .fVaxnA {
+  padding-left: 10px;
+  background-color: $wp-telopea;
+}
+
+// Response code tabs
+.irpqyy > ul > li {
+  background-color: $wp-telopea;
+  border-radius: 3px;
+  &.react-tabs__tab--selected{ color: $cp-blueviolet; }
+  &.tab-error { color: $o-fire; }
+  &.tab-success { color: $gr-viridian; }
+}
+
+// Request methods
+.bNYCAJ,
+.jBjYbV,
+.hOczRB,
+.fRsrDc,
+.hPskZd {
+  font-family: $rubik;
+  font-weight: $medium;
+  letter-spacing: .04em;
+  border-radius: 3px;
+}
+.bNYCAJ { background-color: $b-curious; } /* Post */
+.jBjYbV { background-color: $gr-canopy; } /* Get */
+.hOczRB { background-color: $cp-comet; } /* Put */
+.fRsrDc { background-color: $ch-chartreuse; color: $ch-olive; } /* Patch */
+.hPskZd { background-color: $o-curacao; } /* Delete */
+
+// Content type block
+.gzAoUb {
+  background-color: rgba($wp-jagger, .4);
+  font-family: $rubik;
+}
+.iENVAs { font-family: $roboto-mono; }
+.dpMbau { font-family: $rubik; }
+
+// Code controls
+.fCJmC {
+  font-family: $rubik;
+  span { border-radius: 3px; }
+}
+
+// Code blocks
+.kZHJcC { font-family: $roboto-mono; }
+.jCgylq {
+  .token.string {
+    color: $gr-honeydew;
+    & + a { color: $b-malibu; }
+  }
+  .token.boolean { color: #f955b0; }
+}
--- a/assets/styles/styles-api.scss
+++ b/assets/styles/styles-api.scss
@ -0,0 +1,4 @@
+// InfluxData API Docs style overrides
+// These override styles generated by ReDoc
+
+@import "layouts/api-overrides";
--- a/content/v2.0/query-data/execute-queries.md
+++ b/content/v2.0/query-data/execute-queries.md
@ -86,9 +86,9 @@ curl http://localhost:9999/api/v2/query?org=my-org -XPOST -sS \
  -H 'Authorization: Token YOURAUTHTOKEN' \
  -H 'Accept: application/csv' \
  -H 'Content-type: application/vnd.flux' \
-  -d 'from(bucket:“test”)
+  -d 'from(bucket:"example-bucket")
        |> range(start:-1000h)
-        |> group(columns:[“_measurement”], mode:“by”)
+        |> group(columns:["_measurement"], mode:"by")
        |> sum()'
 ```
 {{% /code-tab-content %}}
@ -100,9 +100,9 @@ curl http://localhost:9999/api/v2/query?org=my-org -XPOST -sS \
  -H 'Accept: application/csv' \
  -H 'Content-type: application/vnd.flux' \
  -H 'Accept-Encoding: gzip' \
-  -d 'from(bucket:“test”)
+  -d 'from(bucket:"example-bucket")
        |> range(start:-1000h)
-        |> group(columns:[“_measurement”], mode:“by”)
+        |> group(columns:["_measurement"], mode:"by")
        |> sum()'
 ```
 {{% /code-tab-content %}}
--- a/content/v2.0/reference/api.md
+++ b/content/v2.0/reference/api.md
@ -15,15 +15,37 @@ Access the InfluxDB API using the `/api/v2/` endpoint.
 InfluxDB uses [authentication tokens](/v2.0/security/tokens/) to authorize API requests.
 Include your authentication token as an `Authorization` header in each request.

+{{< code-tabs-wrapper >}}
+{{% code-tabs %}}
+[InfluxDB OSS](#)
+[InfluxDB Cloud](#)
+{{% /code-tabs %}}
+{{% code-tab-content %}}
 ```sh
-curl --request GET \
-  --url http://localhost:9999/api/v2/ \
+curl --request POST \
+  --url http://localhost:9999/api/v2/write?org=my-org&bucket=example-bucket \
  --header 'Authorization: Token YOURAUTHTOKEN'
 ```
+{{% /code-tab-content %}}
+{{% code-tab-content %}}
+```sh
+# Use the hostname of your InfluxDB Cloud UI
+curl --request POST \
+  --url https://us-west-2-1.aws.cloud2.influxdata.com/api/v2/write?org=my-org&bucket=example-bucket \
+  --header 'Authorization: Token YOURAUTHTOKEN'
+```
+{{% /code-tab-content %}}
+{{< /code-tabs-wrapper >}}

-## View Influx v2 API Documentation
-Full InfluxDB v2 API documentation is built into the `influxd` service.
-To view the API documentation, [start InfluxDB](/v2.0/get-started/#start-influxdb)
-and visit the `/docs` endpoint in a browser.
+## View InfluxDB v2 API Documentation
+<a class="btn" href="/v2.0/api/">InfluxDB v2.0 API documentation</a>

-<a class="btn" href="http://localhost:9999/docs" target="\_blank">localhost:9999/docs</a>
+### View InfluxDB API documentation locally
+InfluxDB API documentation is built into the `influxd` service and represents
+the API specific to the current version of InfluxDB.
+To view the API documentation locally, [start InfluxDB](/v2.0/get-started/#start-influxdb)
+and visit the `/docs` endpoint in a browser ([localhost:9999/docs](http://localhost:9999/docs)).
+
+## InfluxDB client libraries
+InfluxDB client libraries are language-specific packages that integrate with the InfluxDB v2 API.
+For information about supported client libraries, see [InfluxDB client libraries](/v2.0/reference/client-libraries/).
--- a/content/v2.0/write-data/best-practices/optimize-writes.md
+++ b/content/v2.0/write-data/best-practices/optimize-writes.md
@ -11,8 +11,13 @@ v2.0/tags: [best practices, write]

 Use these tips to optimize performance and system overhead when writing data to InfluxDB.

-_[Telegraf](/v2.0/write-data/use-telegraf/), [InfluxDB scrapers](/v2.0/write-data/scrape-data/),
-and many [InfluxDB client libraries](/v2.0/reference/client-libraries/) employ these optimizations by default._
+{{% note %}}
+The following tools write to InfluxDB and employ write optimizations by default:
+
+- [Telegraf](/v2.0/write-data/use-telegraf/)
+- [InfluxDB scrapers](/v2.0/write-data/scrape-data/)
+- [InfluxDB client libraries](/v2.0/reference/client-libraries/)
+{{% /note %}}

 ---

--- a/layouts/_default/api.html
+++ b/layouts/_default/api.html
@ -0,0 +1 @@
+{{ .Content }}
--- a/layouts/partials/header/stylesheets.html
+++ b/layouts/partials/header/stylesheets.html
@ -5,6 +5,7 @@
 {{ $cssOptionsLight := (dict "targetPath" "light-theme.css" "outputStyle" "compressed" "enableSourceMap" true) }}
 {{ $cssSidebarOpen := (dict "targetPath" "sidebar-open.css" "outputStyle" "compressed" "enableSourceMap" true) }}
 {{ $cssSidebarClose := (dict "targetPath" "sidebar-closed.css" "outputStyle" "compressed" "enableSourceMap" true) }}
+{{ $cssAPIOverrides := (dict "targetPath" "api.css" "outputStyle" "compressed" "enableSourceMap" true) }}
 {{ $PostCSSOptions := (dict "use" "autoprefixer" "noMap" false) }}

 {{ $stylesLight := resources.Get "styles/styles-default.scss" | toCSS $cssOptionsLight | postCSS $PostCSSOptions | fingerprint }}
@ -18,3 +19,6 @@

 {{ $stylesSidebarClosed := resources.Get "styles/sidebar-closed.scss" | toCSS $cssOptionsLight | postCSS $PostCSSOptions | fingerprint }}
 <link rel="alternate stylesheet" title="sidebar-closed" type="text/css" href="{{ $stylesSidebarClosed.RelPermalink }}">
+
+{{ $stylesAPIOverrides := resources.Get "styles/styles-api.scss" | toCSS $cssAPIOverrides | postCSS $PostCSSOptions }}
+<link rel="stylesheet" type="text/css" href="{{ $stylesAPIOverrides.RelPermalink }}">