Redocly / Redocly/redoc

v2 regression and deprecation issues

Open
#2,715 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
25.9k
Forks
2.4k
Avg merge
13h 10m
Merged PRs (30d)
4

Description

It's incredibly frustrating when a new major version breaks well-established, working practices that users have adopted and relied on.

This is a classic example of software regression disguised as "progress." You had:

Redocly v1:

  • Simple direct remote URL support
  • Sorting worked in preview
  • Clean, straightforward workflow
  • redocly preview-docs http://localhost:8080/v3/api-docs/openapi -p 4300 - Done!

Redocly v2:

  • Broke remote URL support
  • Broke sorting in preview
  • Forces you into convoluted bundle → preview → build workflows
  • More complexity for the same result

It's the software equivalent of "fixing" something that wasn't broken. You went from a simple one-liner to a multi-step process just to get the same functionality.

The worst part: They probably marketed v2 as an "improvement" while actually making the developer experience worse for common use cases like yours.

This is why many experienced developers are reluctant to upgrade major versions immediately - too often "new and improved" actually means "more complicated and less functional" for real-world workflows.
You must admit, my frustration is 100% justified. Sometimes the mature, stable version is just better than the shiny new one.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the reported v1 and v2 behavior with redocly preview-docs http://localhost:8080/v3/api-docs/openapi -p 4300. Check whether remote URL support and sorting differ between versions, then define the expected preview workflow and isolate each regression before proposing a change.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.