add an 'API Reference' top level nav in docs:

- for local build, just point to http://localhost:30870/api/redoc
- for deployment, copy locally from prod and serve at /api/
- add copy-api-docs.sh to copy openapi.json, redoc and logo to /api/ dir
- for local testing, run copy-api-docs.sh and then run mkdocs serve
- fixes #1582

.github/workflows/docs-publish.yaml

@@ -21,6 +21,11 @@ jobs:
       - name: Generate Helm Chart Index
         run: python ./scripts/generate-helm-index.py > ./frontend/docs/docs/helm-repo/index.yaml
 
+      - name: Copy Docs Files
+        run: frontend/docs/copy-api-docs.sh
+        env:
+          DOCS_SOURCE_URL: https://app.browsertrix.com
+
       - name: Build Docs
         run: cd frontend/docs; mkdocs gh-deploy --force
         env:

frontend/Dockerfile

@@ -44,7 +44,7 @@ RUN pip install mkdocs-material
 COPY --link ./docs/mkdocs.yml .
 COPY --link ./docs/docs ./docs
 
-RUN mkdocs build
+RUN API_DOCS_URL=/api/redoc mkdocs build
 
 FROM docker.io/library/nginx:1.23.2
 

frontend/docs/copy-api-docs.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+CURR=$(dirname "${BASH_SOURCE[0]}")
+
+TARGET=$CURR/docs/api/
+mkdir $TARGET
+curl "$DOCS_SOURCE_URL/api/openapi.json" > $TARGET/openapi.json
+curl "$DOCS_SOURCE_URL/api/redoc" > $TARGET/index.html
+curl "$DOCS_SOURCE_URL/docs-logo.svg" > $TARGET/../docs-logo.svg

frontend/docs/docs/index.md

@@ -15,6 +15,7 @@ Docs are organized into the following sections:
 - [User Guide](./user-guide/index.md) — Instructions on how to use Browsertrix to create and share web archives.
 - [Self-Hosting](./deploy/index.md) — Instructions on how to install, set up, and deploy self-hosted Browsertrix.
 - [Development](./develop/index.md) — Contribute to the open source development of Browsertrix software.
+- [API Reference](/api) - Full API reference for interacting with the Browsertrix backend.
 
 If you have feedback on the docs, please feel free to [reach out to us](mailto:docs-feedback@webrecorder.net).
 

frontend/docs/mkdocs.yml

@@ -91,6 +91,9 @@ nav:
       - develop/localization.md
       - develop/docs.md
 
+  - API Reference: !ENV [ API_DOCS_URL, "/api/" ]
+
+
 markdown_extensions:
   - toc:
       toc_depth: 3