# Which Problems Are Solved
- Generated V1 API reference docs are missing their base path prefixes
(e.g. `/admin/v1`, `/auth/v1`, `/management/v1`, `/system/v1`).
- Endpoint pages show routes like `/healthz` instead of
`/admin/v1/healthz`.
This happens because V1 protos still define `base_path` via legacy
OpenAPI v2 swagger annotations, while docs generation uses
`protoc-gen-connect-openapi`, which ignores those annotations and emits
the bare `google.api.http` paths.
# How the Problems Are Solved
- After OpenAPI generation in
`apps/docs/scripts/generate-proto-docs.mjs`, apply a small hardcoded map
of the four legacy V1 services and prepend the correct prefix to each
path in the generated specs.
- The rewrite is idempotent (`startsWith(prefix)`), so already-prefixed
paths are left alone.
- Because the prefixes are written into the generated OpenAPI files,
Fumadocs MDX generation and runtime page rendering stay in sync.
# Additional Changes
- None.
# Additional Context
- V1 APIs are legacy and frozen; hardcoding the four known prefixes is
simpler and more reliable than dynamically scraping `.proto` files.
- Changing the protos or dual-generating with `openapiv2` would be much
more invasive for a docs-only issue.
- Verified locally for Admin, Auth, Management, and System pages (e.g.
`/admin/v1/healthz`, `/management/v1/users/{id}`).
---------
Co-authored-by: Livio Spring <9405495+livio-a@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
(cherry picked from commit 87538f29e1)
# Which Problems Are Solved
For switching v4.x releases to a corresponding maintenance branch, we
had to trick semantic release and create a `5.0.0-base` tag on main.
This now breaks the docs build, which tries to fetch all tags and build
a corresponding version.
# How the Problems Are Solved
- Ignore pre-released tags/releases for the moment.
# Additional Changes
None
# Additional Context
- requires backport to v4.x
(cherry picked from commit 85ce8c153b)
# Which Problems Are Solved
For existing customers it could be hard to understand the new aligned
terms we have defined, if they are already used to the "old term"
# How the Problems Are Solved
Adding notes at the top of docs pages to state clearliy new and old
terms.
(cherry picked from commit 9a4530bf77)
# Which Problems Are Solved
- `@zitadel/docs:generate-proto-docs` could block while `npx` waited for
confirmation to install `@bufbuild/buf`.
- When the docs generation ran through `nx run-many --target generate`,
that interactive prompt was hidden, so the task appeared stuck without
visible output.
# How the Problems Are Solved
- Resolve Buf from the workspace root with `pnpm exec buf generate` so
the repo-pinned CLI is used non-interactively.
- Run the Buf command from the workspace context instead of the
temporary execution directory.
- Keep the existing generation arguments, template handling, and
excluded path handling intact.
# Additional Changes
- Remove the temporary directory setup that was only needed for the
previous `npx`-based invocation.
- Keep the existing `protoc-gen-connect-openapi` installation and PATH
wiring unchanged.
# Additional Context
- Follow-up for the docs generation issue discussed in Discord where
`@zitadel/docs:generate-proto-docs` prompted for `@bufbuild/buf`
installation and appeared blocked under `nx run-many --target generate`.
- Validated with `pnpm nx run @zitadel/docs:generate-proto-docs
--outputStyle=stream`.
- Validated with `pnpm nx run @zitadel/docs:generate
--outputStyle=stream`.
(cherry picked from commit 238d98bb30)
Federico Coppede
Livio Spring
Fabienne Bühler
Florian Forster
Mridang Agarwalla
Vitor Bari Buccianti
Livio Spring