From f474f21c1ee8940c6ba3c80df1130be3cf874cf3 Mon Sep 17 00:00:00 2001 From: Scott Anderson Date: Mon, 30 Sep 2019 10:16:09 -0600 Subject: [PATCH] api-doc readme and script comments --- api-docs/README.md | 31 ++++++++++++++++++++++++++++++- api-docs/generate-api-docs.sh | 2 ++ 2 files changed, 32 insertions(+), 1 deletion(-) diff --git a/api-docs/README.md b/api-docs/README.md index 653ae6b68..43939b949 100644 --- a/api-docs/README.md +++ b/api-docs/README.md @@ -1,7 +1,36 @@ ## 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`. -- Versioned swagger files +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 ``` diff --git a/api-docs/generate-api-docs.sh b/api-docs/generate-api-docs.sh index a9419c248..1f80e8a21 100644 --- a/api-docs/generate-api-docs.sh +++ b/api-docs/generate-api-docs.sh @@ -35,6 +35,8 @@ weight: 102 # 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