FD-880: Migrate redoc-cli to @redocly/cli

[KARSE22]

Jira

FD-880

Description

Migrates the docs toolchain from the deprecated redoc-cli to @redocly/cli.

Changes

package.json

• Replace redoc-cli (devDependency) with @redocly/cli@^2.31.5
• Remove patch-package dependency and postinstall patch-package hook
• Update redoc script from redoc-cli build to redocly build-docs; drop --options=docs/redocOptions.json (config moved to .redocly.yaml)

.redocly.yaml

• Migrate theme/display options from docs/redocOptions.json into .redocly.yaml under theme.openapi
• Fix disallowAdditionalProperties → allowAdditionalProperties: true

.github/workflows/cd.yml

• Replace hilary/openapi-cli-bundle-action@v0.0.2 with npm ci && npm run bundle
• Split bundling and docs build into separate steps
• Rename step from "build zero-dependency docs" to "build docs"
• Remove unused extract_branch step

.github/workflows/ci.yml

• Replace npm i prettier && npm run pretty with npm ci && npm run pretty:check to enforce Prettier as a check rather than auto-fixing

Deleted

• docs/redocOptions.json — config moved to .redocly.yaml
• patches/redoc-cli+0.13.16.patch — no longer needed

docs/README.md

• Update tool reference from redoc-cli to @redocly/cli
• Drop stale "zero-dependency" claim

[guardrails]

All previously detected findings have been fixed. Good job! 👍🎉

We will keep this comment up-to-date as you go along and notify you of any security issues that we identify.

---

👉 Go to the dashboard for detailed results.

📥 Happy? Share your feedback with us.

[gemini-code-assist]

Code Review

This pull request migrates the documentation generation from redoc-cli to @redocly/cli, consolidating the configuration into .redocly.yaml and removing obsolete dependencies. It also attempts to upgrade the Node.js environment to version 24. However, several critical issues were identified: Node.js version 24 is not yet released, which will break the build in the Dockerfile, GitHub Actions, and package engine requirements. Additionally, @redocly/cli does not support dot-notation for template options in the package.json script, meaning these options must be moved to a JSON file to prevent template variables from rendering empty. Finally, a minor CSS syntax issue with a trailing semicolon in the font-family configuration needs to be corrected.

[gemini-code-assist]

Unlike redoc-cli (which used yargs and supported dot-notation for object arguments), @redocly/cli uses a different argument parser that does not support passing individual template options via --templateOptions.key=value flags. Instead, @redocly/cli expects --templateOptions to point to a JSON file containing the options.\n\nIf you run this command as-is, the template options will be ignored, and all the custom template variables (like {{templateOptions.LOB_URL}}, {{templateOptions.segmentKey}}, etc.) in actions/redoc/template.hbs will render as empty strings, breaking links, images, and analytics in the generated docs.\n\nTo fix this, create a JSON file (e.g., docs/templateOptions.json) with the template options and reference it using --templateOptions docs/templateOptions.json.

Suggested change

"redoc": "redocly build-docs $npm_package_config_specfile -t actions/redoc/template.hbs --templateOptions.segmentKey=0ysbW8vXHeRAnY2saZPMlRSZFfPwd1RO --templateOptions.SUPPORT_URL=https://support.lob.com/hc/en-us --templateOptions.LOB_ASSETS_URL=https://s3-us-west-2.amazonaws.com/public.lob.com --templateOptions.canonicalUrl=https://docs.lob.com/ --templateOptions.keywords=\"Direct Mail, Address Verification\" --templateOptions.description=\"Detailed developer documentation for Lob's address verification API and print & mail API. Learn how to easily integrate Lob's APIs within your product or technology stack.\" --templateOptions.LOB_URL=https://lob.com --templateOptions.image=https://s3-us-west-2.amazonaws.com/public.lob.com/dashboard/navbar/lob-logo.svg --templateOptions.DASHBOARD_URL=https://dashboard.lob.com/# --templateOptions.HELP_URL=https://help.lob.com/ --templateOptions.LOB_BACKUP_ASSETS_URL=https://assets-global.website-files.com/5e1e5c62fa3d4447af417098/ --title=\"Lob API documentation\" -o docs/index.html",

"redoc": "redocly build-docs $npm_package_config_specfile -t actions/redoc/template.hbs --templateOptions docs/templateOptions.json --title=\"Lob API documentation\" -o docs/index.html",

[KARSE22]

I don’t think this applies to the Redocly CLI version in this PR. redocly build-docs --help documents dot notation for --templateOptions, and the generated docs/index.html confirms these values are being rendered correctly: templateOptions.LOB_URL, canonicalUrl, image URLs, etc. are populated.

Also, from the CLI implementation, templateOptions is passed through from parsed argv, while JSON/file parsing is applied to --theme/openapi options. So changing this to --templateOptions docs/templateOptions.json may actually make templateOptions a string path rather than the object expected by the template.

[KARSE22]

Question: are we OK with the generated docs now depending on Redocly’s CDN for the core Redoc runtime?

Before this PR, docs/index.html embedded redoc.standalone.js inline. After the migration, it loads https://cdn.redocly.com/redoc/v2.5.1/bundles/redoc.standalone.js.

The page already had other external assets, so it was not fully offline before, but this is a new external dependency for the docs renderer itself. If the "zero dependency" is intentional, I think I can preserve the old behavior with a small post-build inlining step.