chore(docs): add openapi specs to docs

Primary Changes
1. Updated deploy_docs workflow to generate markdown for openapi
    specs files present across packages

Secondary Changes required to incorporate 1)
2. Added docs/scripts/publish_openapi.py to generate markdown
3. Added swagger-ui-tag plugin to mkdocs
4. Updated docs/requirements.txt for the above plugin to be
   downloaded.

Signed-off-by: Jennifer Bell <jenniferlianne@gmail.com>

.github/workflows/deploy_docs.yml

@@ -8,16 +8,27 @@ on:
   push:
     branches:
       - main
+
     paths:
       - 'docs/**'
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
+
+env:
+  SITE_URL: https://${{ github.repository_owner }}.github.io/cacti
+  NODEJS_VERSION: v18.18.2
+
 
 jobs:
   deploy-docs:
     runs-on: ubuntu-22.04
     steps:
+      - name: Use Node.js ${{ env.NODEJS_VERSION }}
+        uses: actions/setup-node@v4.0.2
+        with:
+          node-version: ${{ env.NODEJS_VERSION }}
+
       # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
       - uses: actions/checkout@v4.1.1
 
@@ -30,6 +41,12 @@ jobs:
       - name: Install dependencies
         run: pip install -r requirements.txt
         working-directory: docs
+
+      - name: Build packages
+        run: npm run configure
+
+      - name: Build markdown for openapi specs
+        run: 'python3 docs/scripts/publish_openapi.py'
 
       - name: Build and publish
         run: git pull && mkdocs gh-deploy

.gitignore

@@ -5,6 +5,7 @@ target/
 .DS_Store
 node_modules/
 docs/main
+docs/docs/references/openapi
 logs/
 jspm_packages/
 generated-sources/

docs/docs/index.md

@@ -29,6 +29,7 @@ Client libraries and examples are provided in the following languages: JavaScrip
 * [Weaver RFCs](https://github.com/hyperledger/cacti/tree/main/weaver/rfcs)
 * [Running pipelines with Cactus packages](./cactus/)
 * [Running pipelines with Weaver packages](./weaver/)
+* [Open API Specifications](./references/openapi/index.md)
 
 !!! note
 

docs/docs/references/openapi/index.md

@@ -0,0 +1 @@
+# THIS PAGE GENERATED AUTOMATICALLY IN CI by docs/scripts/publish_openapi.py

docs/mkdocs.yml

@@ -1,5 +1,5 @@
 site_name: Using and Developing with Hyperledger Cacti
-site_url: https://hyperledger.github.io/cacti
+site_url: !ENV [SITE_URL, 'https://hyperledger.github.io/cacti']
 repo_name: hyperledger/cacti
 repo_url: https://github.com/hyperledger/cacti
 theme:
@@ -74,6 +74,7 @@ markdown_extensions:
   - pymdownx.tilde
 plugins:
   - search
+  - swagger-ui-tag
   - mike
 extra:
   analytics:
@@ -192,6 +193,7 @@ nav:
     - Business Usage: references/business.md
     - Project Best Practices: references/best-practices.md
     - GitHub Contributions: references/github.md
+    - OpenAPI Specs: references/openapi/index.md
   - Contributing:
     - How to Contribute: contributing/how-to-contribute.md
     - Reporting a Bug: contributing/reporting-a-bug.md

docs/requirements.txt

@@ -1,2 +1,3 @@
 mkdocs-material
 mike
+mkdocs-swagger-ui-tag

docs/scripts/publish_openapi.py

@@ -0,0 +1,73 @@
+import os
+import os.path
+import subprocess
+import json
+import shutil
+
+# Package openapi markdown for publishing as documentation
+#
+# - Copies any package openapi.json file in the dist directory to docs/docs/openapi/json 
+# - Generates an openapi .md file to view the openapi.json file in docs/docs/openapi
+# - Generates an index file of all openapi markdown files, grouped by base directory
+
+apis_by_group = {}
+
+doc_dir = "docs/docs/references/openapi"
+json_dir = f"{doc_dir}/json"
+
+def write_mdfile(component, src):
+    mdfile_name = f"{doc_dir}/{component}_openapi.md"
+    with open(mdfile_name, 'w') as f:
+        f.write(f"<swagger-ui src=\"./{src}\"/>")
+    return mdfile_name
+
+def copy_openapi(component, openapi_file):
+    new_filename = f"json/{component}-openapi.json"
+    shutil.copy(openapi_file, f"{doc_dir}/{new_filename}")
+    return new_filename
+
+def publish_openapi(component, openapi_file):
+    src_file = copy_openapi(component, openapi_file)
+    md_file = write_mdfile(component, src_file)
+
+def write_index(api_groups):
+    with open(f"{doc_dir}/index.md", 'w') as f:
+        f.write(f"---\n")
+        f.write("title: All Cacti Open API Specifications\n")
+        f.write("---\n")
+        groups = list(api_groups.keys())
+        groups.sort(reverse=True)
+        for group in groups:
+            components = api_groups[group]
+            f.write(f"##{group.capitalize()}\n")
+            components.sort()
+            for component in components:
+                f.write(f" * [{component}](./{component}_openapi.md)\n")
+
+def get_openapi_files(root_dir):
+    openapi_files = []
+    for dirpath, dirnames, filenames in os.walk(root_dir + "/dist"):
+        for filename in [f for f in filenames if f.endswith("openapi.json")]:
+            openapi_files.append(os.path.join(dirpath, filename))
+    return openapi_files
+
+
+if not os.path.exists(json_dir):
+    os.makedirs(json_dir)
+
+package_list_str = subprocess.run(["npx lerna ls --json"], shell=True, capture_output=True, text=True)
+package_list = json.loads(package_list_str.stdout)
+
+for package in package_list:
+    location_path = package['location'].split('/')
+    root_dir = len(location_path) - location_path[::-1].index('cacti') # no rindex implemented
+    package_group = location_path[root_dir]
+    for openapi_file in get_openapi_files(package['location']):
+        if not package_group in apis_by_group:
+            apis_by_group[package_group] = []
+        package_basename = package['name'].replace('@hyperledger/','')
+        publish_openapi(package_basename, openapi_file)
+        print(f"{package_group} : {package_basename}")
+        apis_by_group[package_group].append(package_basename)
+
+write_index(apis_by_group)