migrate from redoc to redocly cli (#9066)

* use redocly cli

* move dependency

* try using local install of redocly with npx

* tidy up

* tiny change to name of API build tool

* remove dependency that is not needed

* minimise config and add lint command

* streamlining

* bundle to remove unused components before linting and building

.circleci/config.yml

@@ -175,7 +175,7 @@ jobs:
           name: Build API 1.x documentation with Slate
           command: ./scripts/build_api_docs.sh -v1
       - run:
-          name: Build API 2.x documentation with Redoc
+          name: Build API 2.x documentation with Redocly
           command: ./scripts/build_api_docs.sh -v2
       - persist_to_workspace:
           root: *workspace_root

scripts/build_api_docs.sh

@@ -18,16 +18,20 @@ build_api_v1() {
 # c) run the spec through redoc-cli, outputting a single html file.
 # d) move the file into our temporary workspace, created in .circleci/config.yml
 build_api_v2() {
-    echo "Building API v2 documentation with Redoc"
+    echo "Building API v2 documentation with Redocly CLI"
     cd src-api;
     echo "Fetching OpenAPI spec."
     curl https://circleci.com/api/v2/openapi.json > openapi.json
     echo "Adding code samples to openapi.json spec."
     ./node_modules/.bin/snippet-enricher-cli --targets="node_request,python_python3,go_native,shell_curl" --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 --template "../src-api/v2/template.hbs"
+    jq -s '.[0] * .[1]' openapi-with-examples.json openapi-patch.json > openapi-patched.json
+    echo Bundle api docs and remove unused components
+    npx redocly bundle openapi-patched.json --remove-unused-components --output openapi-final.json
+    echo "Lint API docs"
+    npx redocly lint openapi-final.json
+    echo "Build docs with redocly cli."
+    npx redocly build-docs openapi-final.json
     echo "Moving build redoc file to api/v2"
     mv redoc-static.html index.html
 }

src-api/package.json

@@ -13,9 +13,8 @@
   "author": "",
   "license": "ISC",
   "devDependencies": {
-    "openapi-snippet": "^0.14.0",
-    "redoc-cli": "^0.13.0",
-    "snippet-enricher-cli": "0.0.8"
+    "snippet-enricher-cli": "0.0.8",
+    "@redocly/cli": "^1.25.11"
   },
   "resolutions": {
     "braces": "3.0.3"

src-api/redocly.yml

@@ -0,0 +1,2 @@
+extends:
+  - recommended