Merge pull request circleci#4669 from circleci/tjs/swap-redoc

API v2 Slate -> Redoc

Author: teesloane

.circleci/config.yml

@@ -207,12 +207,12 @@ jobs:
       - ruby-deps:
           dir: src-api
       - restore_cache:
-          key: circleci-docs-v1-{{ .Branch }}-{{ checksum "src-api/package-lock.json"}}
+          key: circleci-docs-v2-{{ .Branch }}-{{ checksum "src-api/package-lock.json"}}
       - run:
           name: Install Node dependencies
           command: cd src-api; npm install
       - save_cache:
-          key: circleci-docs-v1-{{ .Branch }}-{{ checksum "src-api/package-lock.json"}}
+          key: circleci-docs-v2-{{ .Branch }}-{{ checksum "src-api/package-lock.json"}}
           paths:
             - src-api/node_modules
       - run:
@@ -309,7 +309,7 @@ jobs:
       ### NOTE: we are ignore some files in the HTML proofer as it fails on pending translated docs.
       - run:
           name: Test with HTMLproofer
-          command: bundle exec htmlproofer jekyll/_site --allow-hash-href --check-favicon --check-html --disable-external --file-ignore "/docs/ja/2.0/security-server/,/docs/ja/2.0/v.2.19-overview/,/docs/ja/2.0/customizations/,/docs/ja/2.0/aws-prereq/,/docs/ja/2.0/ops/,/docs/ja/2.0/about-circleci/,/docs/ja/2.0/demo-apps/,/docs/ja/2.0/google-auth/,/docs/ja/2.0/orb-concepts/,/docs/ja/2.0/tutorials/,/docs/reference-2-1/" --empty-alt-ignore 2>&1 | nkf -w --url-input | tee $JOB_RESULTS_PATH/htmlproofer-results.txt
+          command: bundle exec htmlproofer jekyll/_site --allow-hash-href --check-favicon --check-html --disable-external --file-ignore "jekyll/_site/docs/api/v2/index.html,docs/api/v2/,/docs/ja/2.0/security-server/,/docs/ja/2.0/v.2.19-overview/,/docs/ja/2.0/customizations/,/docs/ja/2.0/aws-prereq/,/docs/ja/2.0/ops/,/docs/ja/2.0/about-circleci/,/docs/ja/2.0/demo-apps/,/docs/ja/2.0/google-auth/,/docs/ja/2.0/orb-concepts/,/docs/ja/2.0/tutorials/,/docs/reference-2-1/" --empty-alt-ignore 2>&1 | nkf -w --url-input | tee $JOB_RESULTS_PATH/htmlproofer-results.txt
 
       - store_artifacts: # stores the built files of the Jekyll site
           path: jekyll/_site/docs/

README.md

@@ -36,9 +36,25 @@ this folder (in our build process) and integrated into the Jekyll Site. Follow
 the [local development guide](./docs/local-development.md) to get started with
 building the Jekyll site.
 
-### `/src-api` - API V2 Build Tooling
+`/src-api` - API v1.1 and v2 Build Tooling
 
-This is the build tooling we use for automatically generating documentation for
+Our API documentation source can be found in this folder.
+
+**API v1** is written by hand, and compiled to work with
+[Slate](https://github.com/slatedocs/slate). The compilation and deployment of
+`v1` is handled by our `.circleci/config.yml`, which calls our `build_api_docs`
+script. If you need to make changes to our V1 documentation, go to
+`src-api/source/includes` and make changes as needed in the markdown files.
+
+API v2 is compiled from an [OpenAPI
+spec](https://github.com/OAI/OpenAPI-Specification). We use
+[Redoc](https://github.com/Redocly/redoc) to compile our spec into a webpage. To
+see the compilation process, refer to `build_api_docs.sh` and our
+`.circleci/config.yml`. If you need to make changes to the output site, you will
+likely need to make source code changes to the API, where the docs are generated
+from.
+
+This is the build folder we use for automatically generating documentation for
 the CircleCI API v2. This uses [Slate](https://github.com/slatedocs/slate) and
 [Widdershins](https://github.com/Mermade/widdershins) to create documentation
 with a spec (that follows the Open API Spec) generated from the CircleCI code

jekyll/_cci2/api-developers-guide.md

@@ -262,7 +262,10 @@ The following section details the steps you would need, from start to finish, to
     }' https://circleci.com/api/v2/project/{project-slug}/pipeline
     ```
 
-This concludes the end-to-end example of using the V2 API. For more detailed information about other endpoints you may wish to call, please refer to the [CircleCI API v2 Documentation]({{site.baseurl}}/api/v2/#circleci-api) for an overview of all endpoints currently available.
+This concludes the end-to-end example of using the v2 API. For more detailed
+information about other endpoints you may wish to call, please refer to the
+[CircleCI API v2 Documentation]({{site.baseurl}}/api/v2) for an overview of all
+endpoints currently available.
 
 ## Additional API Use Cases
 

jekyll/_cci2/api-intro.md

@@ -73,7 +73,7 @@ In the above example the `project_slug` would take the form `:vcs/:org/:project`
 
 The CircleCI API v2 release includes several new endpoints, and deprecates some others. The sections below list the endpoints added for this release, in addition to the endpoints that have been removed.
 
-For a complete list of all API v2 enpoints, please refer to the [API v2 Reference Guide](https://circleci.com/docs/api/v2/#circleci-api), which contains a detailed description of each individual endpoint, as well as information on required and optional parameters, HTTP status and error codes, and code samples you may use in your workflows.
+For a complete list of all API v2 endpoints, please refer to the [API v2 Reference Guide](https://circleci.com/docs/api/v2/), which contains a detailed description of each individual endpoint, as well as information on required and optional parameters, HTTP status and error codes, and code samples you may use in your workflows.
 
 ### New Endpoints
 

jekyll/_cci2/api-job-trigger.md

@@ -15,7 +15,7 @@ This document describes how to trigger jobs using the CircleCI API.
 
 <div class="alert alert-warning" role="alert">
   <p><span style="font-size: 115%; font-weight: bold;">⚠️ Heads up!</span></p>
-  <span> This document refers to using the legacy CircleCI API 1.0, a service that will be eventually be deprecated in favour of the <a href="https://circleci.com/docs/api/v2/#circleci-api">V2 API</a>. Consider using the <a href="https://circleci.com/docs/api/v2/#trigger-a-new-pipeline">Pipelines</a> endpoints to trigger pipelines.</span>
+  <span> This document refers to using the legacy CircleCI API 1.0, a service that will be eventually be deprecated in favor of the <a href="https://circleci.com/docs/api/v2/">V2 API</a>. Consider using the <a href="https://circleci.com/docs/api/v2/#trigger-a-new-pipeline">Pipelines</a> endpoints to trigger pipelines.</span>
 </div>
 
 

jekyll/_cci2/env-vars.md

@@ -401,7 +401,9 @@ Not all command-line programs take credentials in the same way that `docker` doe
 
 Pipeline parameters can be used to pass variables using the CircleCI API v2. 
 
-A pipeline can be triggered with specific `parameter` values using the API v2 endpoint to [trigger a pipeline]({{site.baseurl}}/api/v2/#trigger-a-new-pipeline). This can be done by passing a `parameters` key in the JSON packet of the `POST` body.
+A pipeline can be triggered with specific `parameter` values using the API v2
+endpoint to [trigger a pipeline]({{site.baseurl}}/api/v2/#operation/getPipelineConfigById). 
+This can be done by passing a `parameters` key in the JSON packet of the `POST` body.
 
 The example below triggers a pipeline with the parameters described in the above config example (NOTE: To pass a parameter when triggering a pipeline via the API the parameter must be declared in the configuration file.).
 

jekyll/_cci2/insights.md

@@ -11,7 +11,7 @@ version:
 
 <div class="alert alert-warning" role="alert">
   <p><span style="font-size: 115%; font-weight: bold;">⚠️ Heads up!</span></p>
-  <span> This document refers to using the Insights page on the CircleCI <i>Server</i> product. If you are interested in accessing insights and analytics for your usage, please consider exploring the <a href="https://circleci.com/docs/api/v2/#circleci-api-insights">Insights endpoints</a> of the CircleCI V2 API.</span>
+  <span> This document refers to using the Insights page on the CircleCI <i>Server</i> product. If you are interested in accessing insights and analytics for your usage, please consider exploring the <a href="https://circleci.com/docs/api/v2/#tag/Insights">Insights endpoints</a> of the CircleCI V2 API.</span>
 </div>
 
 

jekyll/_cci2_ja/api-intro.md

@@ -78,7 +78,7 @@ curl -u ${CIRCLECI_TOKEN}: -X POST --header "Content-Type: application/json" -d
 
 CircleCI API v2 リリースで追加されたエンドポイントもあれば、サポートされなくなったエンドポイントもあります。 以降のセクションに、このリリースで追加されたエンドポイントとサポートされなくなったエンドポイントをまとめています。
 
-API v2 のすべてのエンドポイントは、[API v2 リファレンス ガイド](https://circleci.com/docs/api/v2/#circleci-api)をご覧ください。このガイドには、各エンドポイントの詳細な説明、必須および任意のパラメーターの情報、HTTP ステータスとエラー コード、ワークフローで使用する場合のコード例が掲載されています。
+API v2 のすべてのエンドポイントは、[API v2 リファレンス ガイド](https://circleci.com/docs/api/v2/)をご覧ください。このガイドには、各エンドポイントの詳細な説明、必須および任意のパラメーターの情報、HTTP ステータスとエラー コード、ワークフローで使用する場合のコード例が掲載されています。
 
 ### 新しいエンドポイント
 

jekyll/_includes/global-nav.html

@@ -36,7 +36,7 @@
                   <li class="subnav-item"><a href="{{ '/' | language_relative_url }}">Documentation</a></li>
                   <li class="subnav-item"><a href="https://discuss.circleci.com/" target="_blank">Community Forum</a></li>
                   <li class="subnav-item" ><a href="https://circleci.com/orbs/">Orbs</a></li>
-                  <li class="subnav-item"><a href="https://circleci.com/docs/api/v2/#circleci-api">API</a></li>
+                  <li class="subnav-item"><a href="https://circleci.com/docs/api/v2/">API</a></li>
                   <li class="subnav-item"><a href="{{ '/open-source/' | outer_url }}">Open Source</a></li>
                 </ul>
               </div>
@@ -128,7 +128,7 @@
                 <li class="subnav-item"><a href="{{ '/' | language_relative_url }}">Documentation</a></li>
                 <li class="subnav-item"><a href="https://discuss.circleci.com/" target="_blank">Community Forum</a></li>
                 <li class="subnav-item"><a href="https://circleci.com/orbs/">Orbs</a></li>
-                <li class="subnav-item"><a href="https://circleci.com/docs/api/v2/#circleci-api">API</a></li>
+                <li class="subnav-item"><a href="https://circleci.com/docs/api/v2/">API</a></li>
                 <li class="subnav-item"><a href="{{ '/open-source/' | outer_url }}">Open Source</a></li>
               </ul>
             </li>

scripts/build_api_docs.sh

@@ -16,15 +16,25 @@ build_api_v1() {
     echo "Also - Move /tmp/workspace/api/v1 so default root (api/) displays api v1."
 }
 
-# Fetches the latest api spec and runs widdershins with it.
+# We build our API v2 documentation from an openAPI spec. After fetching the spec we:
+# a) augment the spec using "snippet-enricher-cli" to add code-samples to the spec.
+# b) TODO: merge in any custom code samples we need to alter, using jq.
+# b) run the spec through redoc-cli, outputting a single html file.
+# c) move the file into our temporary workspace, created in .circleci/config.yml
 build_api_v2() {
-    echo "Building API v2 documentation with Slate and Widdershins"
-    cd src-api; rm -r build; rm source/index.html.md
+    echo "Building API v2 documentation with Redoc"
+    cd src-api;
+    echo "Fetching OpenAPI spec."
     curl https://circleci.com/api/v2/openapi.json > openapi.json
-    node node_modules/widdershins/widdershins.js --environment widdershins.apiv2.yml --summary openapi.json -o source/index.html.md
-    bundle exec middleman build --clean --verbose
-    cp -R build/* /tmp/workspace/api/v2
-    echo "Output build moved to /tmp/workspace/api/v2"
+    echo "Adding code samples to openapi.json spec."
+    ./node_modules/.bin/snippet-enricher-cli --targets="node_request,python_python3,go_native,shell_curl,ruby_native" --input=openapi.json  > openapi-with-examples.json
+    echo "Merging in JSON patches to correct and augment the OpenAPI spec."
+    jq -s '.[0] * .[1]' openapi-with-examples.json openapi-patch.json > openapi-final.json
+    echo "Bundling with redoc cli."
+    ./node_modules/.bin/redoc-cli bundle openapi-final.json
+    echo "Moving build redoc file to api/v2"
+    mv redoc-static.html index.html
+    cp index.html /tmp/workspace/api/v2
 }
 
 # build the Config Reference from slate.

src-api/openapi-patch.json

@@ -0,0 +1,30 @@
+{
+  "paths":{
+    "/context":{
+      "get":{
+        "x-codeSamples": [
+          {
+            "lang": "Node + Request",
+            "source": "const request = require('request');\n\nconst options = {\n  method: 'GET',\n  url: 'https://circleci.com/api/v2/context',\n  qs: {\n    'owner-id': 'c65b68ef-e73b-4bf2-be9a-7a322a9df150',\n    'page-token': 'next_page_token'\n  },\n  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}\n};\n\nrequest(options, function (error, response, body) {\n  if (error) throw new Error(error);\n\n  console.log(body);\n});\n"
+          },
+          {
+            "lang": "Python + Python3",
+            "source": "import http.client\n\nconn = http.client.HTTPSConnection(\"circleci.com\")\n\nheaders = { 'authorization': \"Basic REPLACE_BASIC_AUTH\" }\n\nconn.request(\"GET\", \"/api/v2/context?owner-id=c65b68ef-e73b-4bf2-be9a-7a322a9df150&page-token=next_page_token\", headers=headers)\n\nres = conn.getresponse()\ndata = res.read()\n\nprint(data.decode(\"utf-8\"))"
+          },
+          {
+            "lang": "Go + Native",
+            "source": "package main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://circleci.com/api/v2/context?owner-id=c65b68ef-e73b-4bf2-be9a-7a322a9df150&page-token=next_page_token\"\n\n\treq, _ := http.NewRequest(\"GET\", url, nil)\n\n\treq.Header.Add(\"authorization\", \"Basic REPLACE_BASIC_AUTH\")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}"
+          },
+          {
+            "lang": "Shell + Curl",
+            "source": "curl --request GET \\\n  --url 'https://circleci.com/api/v2/context?owner-id=c65b68ef-e73b-4bf2-be9a-7a322a9df150&page-token=next_page_token' \\\n  --header 'authorization: Basic REPLACE_BASIC_AUTH'"
+          },
+          {
+            "lang": "Ruby + Native",
+            "source": "require 'uri'\nrequire 'net/http'\nrequire 'openssl'\n\nurl = URI(\"https://circleci.com/api/v2/context?owner-id=c65b68ef-e73b-4bf2-be9a-7a322a9df150&page-token=next_page_token\")\n\nhttp = Net::HTTP.new(url.host, url.port)\nhttp.use_ssl = true\nhttp.verify_mode = OpenSSL::SSL::VERIFY_NONE\n\nrequest = Net::HTTP::Get.new(url)\nrequest[\"authorization\"] = 'Basic REPLACE_BASIC_AUTH'\n\nresponse = http.request(request)\nputs response.read_body"
+          }
+        ]
+      }
+    }
+  }
+}