Skip to content

feat(poc): generate tsoa openapi spec on deployment #252

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
calthejuggler wants to merge 6 commits into
base: master
Choose a base branch
from
Open

feat(poc): generate tsoa openapi spec on deployment #252

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
59b1ecc
feat(poc): generate tsoa openapi spec
calthejuggler Mar 6, 2026
aa6d300
feat(poc): combine openapi specs with redocly cli
calthejuggler Mar 10, 2026
91a5474
feat(poc): custom merge script
calthejuggler Mar 10, 2026
6dad576
feat(poc): update old spec to use `id` on single id paths
calthejuggler Mar 10, 2026
27f4a34
fix(poc): move /v1 prefix to path level
calthejuggler Mar 10, 2026
29fcea6
fix(poc): attempt to fix double slashes
calthejuggler Mar 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion .github/workflows/build.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,12 @@ jobs:

- name: Install Deps
run: yarn install --frozen-lockfile


- name: Generate Office API spec
run: bash scripts/generate-office-api.sh
env:
ABS_REPO_ACCESS_TOKEN: ${{ secrets.ABS_REPO_ACCESS_TOKEN }}

- name: Clean API
run: yarn clean:api

Expand Down
6 changes: 6 additions & 0 deletions docs/APIs-and-SDKs/Office-API/_category_.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"position": 5,
"collapsed": true,
"collapsible": true,
"label": "Office API"
}
8 changes: 8 additions & 0 deletions docusaurus.config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,14 @@ const config = {
sidebarCollapsed: false,
},
},
office: {
specPath: "office-api-spec.json",
outputDir: "docs/APIs-and-SDKs/Office-API",
sidebarOptions: {
sidebarCollapsible: false,
sidebarCollapsed: false,
},
},
},
},
],
Expand Down
6 changes: 6 additions & 0 deletions netlify.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
[build]
command = "bash scripts/generate-office-api.sh && yarn clean:api && yarn gen:api && yarn build"
publish = "build"

[build.environment]
NODE_VERSION = "24"
9 changes: 9 additions & 0 deletions office-api-spec.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"openapi": "3.0.0",
"info": {
"title": "ABsmartly Office API",
"version": "0.0.0",
"description": "Auto-generated from the latest release branch. Run scripts/generate-office-api.sh with ABS_REPO_ACCESS_TOKEN to update locally."
},
"paths": {}
}
42 changes: 42 additions & 0 deletions scripts/generate-office-api.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
#!/usr/bin/env bash
set -euo pipefail

DOCS_DIR="$(pwd)"

if [ -z "${ABS_REPO_ACCESS_TOKEN:-}" ]; then
echo "No ABS_REPO_ACCESS_TOKEN set, skipping Office API spec generation"
exit 0
fi
Comment on lines +6 to +9

@coderabbitai coderabbitai Bot Mar 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Skip only when missing-token generation is explicitly optional.

exit 0 here turns a missing or revoked token into a green build. Because office-api-spec.json is committed, the rest of the pipeline can still publish stale or empty Office docs instead of failing loudly. Please only no-op for opt-in cases such as untrusted PRs.

🛠️ Possible fix 
 if [ -z "${ABS_REPO_ACCESS_TOKEN:-}" ]; then
-  echo "No ABS_REPO_ACCESS_TOKEN set, skipping Office API spec generation"
-  exit 0
+  echo "ABS_REPO_ACCESS_TOKEN is not set"
+  if [ "${ALLOW_MISSING_OFFICE_API_SPEC:-0}" = "1" ]; then
+    echo "Skipping Office API spec generation"
+    exit 0
+  fi
+  exit 1
 fi
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
if [ -z "${ABS_REPO_ACCESS_TOKEN:-}" ]; then
echo "No ABS_REPO_ACCESS_TOKEN set, skipping Office API spec generation"
exit 0
fi
if [ -z "${ABS_REPO_ACCESS_TOKEN:-}" ]; then
echo "ABS_REPO_ACCESS_TOKEN is not set"
if [ "${ALLOW_MISSING_OFFICE_API_SPEC:-0}" = "1" ]; then
echo "Skipping Office API spec generation"
exit 0
fi
exit 1
fi
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@scripts/generate-office-api.sh` around lines 4 - 7, The script currently
treats a missing ABS_REPO_ACCESS_TOKEN as success; change
scripts/generate-office-api.sh so that if ABS_REPO_ACCESS_TOKEN is missing it
fails the pipeline (exit 1) to avoid silently publishing stale
office-api-spec.json, but allow an explicit opt-in override (e.g., respect a
SKIP_OFFICE_API_GENERATION or UNTRUSTED_PR flag) to no-op when intentionally
requested; update the echo message to indicate why it failed and mention
office-api-spec.json to make the failure clear.


REPO_DIR=$(mktemp -d)
trap "rm -rf $REPO_DIR" EXIT
Comment thread
coderabbitai[bot] marked this conversation as resolved.

echo "Cloning absmartly/abs..."
git clone --no-checkout \
"https://x-access-token:${ABS_REPO_ACCESS_TOKEN}@github.com/absmartly/abs.git" \
"$REPO_DIR"

cd "$REPO_DIR"

# TODO: Once tsoa is in a release branch, switch to auto-detecting latest release:
# LATEST=$(git branch -r \
# | sed 's|origin/||; s/^[[:space:]]*//' \
# | grep -E '^release/[0-9]+-[0-9]+$' \
# | sed 's|release/||' \
# | sort -t'-' -k1,1rn -k2,2rn \
# | head -1)
# BRANCH="release/$LATEST"
BRANCH="vk/d96f-migrate-one-set"
echo "Using branch: $BRANCH"

git sparse-checkout set office/backend office/shared
git checkout "$BRANCH"
Comment on lines +21 to +33

@coderabbitai coderabbitai Bot Mar 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Avoid sourcing the published Office spec from main.

Merging this as-is means the live docs are generated from whatever happens to be on main, not from the released Office backend. Once main drifts, the docs can advertise endpoints or schemas that are not available in production.

🛠️ Possible stopgap until auto-detection lands 
- BRANCH="main"
+ : "${ABS_OFFICE_API_BRANCH:?Set ABS_OFFICE_API_BRANCH to the Office release branch}"
+ BRANCH="$ABS_OFFICE_API_BRANCH"
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
# TODO: Once tsoa is in a release branch, switch to auto-detecting latest release:
# LATEST=$(git branch -r \
# | sed 's|origin/||; s/^[[:space:]]*//' \
# | grep -E '^release/[0-9]+-[0-9]+$' \
# | sed 's|release/||' \
# | sort -t'-' -k1,1rn -k2,2rn \
# | head -1)
# BRANCH="release/$LATEST"
BRANCH="main"
echo "Using branch: $BRANCH"
git sparse-checkout set office/backend office/shared
git checkout "$BRANCH"
# TODO: Once tsoa is in a release branch, switch to auto-detecting latest release:
# LATEST=$(git branch -r \
# | sed 's|origin/||; s/^[[:space:]]*//' \
# | grep -E '^release/[0-9]+-[0-9]+$' \
# | sed 's|release/||' \
# | sort -t'-' -k1,1rn -k2,2rn \
# | head -1)
# BRANCH="release/$LATEST"
: "${ABS_OFFICE_API_BRANCH:?Set ABS_OFFICE_API_BRANCH to the Office release branch}"
BRANCH="$ABS_OFFICE_API_BRANCH"
echo "Using branch: $BRANCH"
git sparse-checkout set office/backend office/shared
git checkout "$BRANCH"
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@scripts/generate-office-api.sh` around lines 19 - 31, The script currently
hardcodes BRANCH="main" and then runs git checkout "$BRANCH", which causes docs
to be built from main instead of a released Office backend; change the logic so
BRANCH is resolved to the latest release branch or tag (or read from an explicit
environment variable like OFFICE_TSOA_BRANCH) instead of defaulting to "main",
and fail loudly if no release branch/tag can be determined; update the code
paths that reference BRANCH and the git checkout call to use this resolved
release identifier so generated docs always come from a released Office backend.


cd office/shared/lib
npm ci
cd ../../backend
npm ci --ignore-scripts
npx tsoa spec

cp src/generated/openapi.json "${DOCS_DIR}/office-api-spec.json"
echo "Office API spec generated successfully from $BRANCH"