feat: add disallowDefault option to operation-2xx-response

[dimitropoulos]

What/Why/How?

Adds disallowDefault to operation-2xx-response. Default false, so nothing changes unless you opt in.

Here at Cloudflare, this is causing code-generation to fail. Today default satisfies the rule, so an operation whose only response is default passes. But our code generator reads the 2xx response to produce the operation's return type. default is the catch-all for responses that aren't listed, so there's no success shape to model in codegen, and the generated client ends up with an untyped or empty result - so it breaks downstream

disallowDefault: true requires an explicit 2xx.

rules:
  operation-2xx-response:
    severity: error
    disallowDefault: true

Threaded through validateResponseCodes, which guards the clause on codeRange === '2XX', so operation-4xx-response is unaffected.

Reference

The clause this gates: validateResponseCodes in packages/core/src/rules/utils.ts.

Testing

Added a rule test for disallowDefault: false on a default-only operation. Existing tests cover the unchanged default. Full unit suite passes; the 9 tests/e2e/respect/ failures are pre-existing on main.

Check yourself

• This PR follows the contributing guide
• All new/updated code is covered by tests
• Core code changed? - Tested with other Redocly products (internal contributions only)
• New package installed? - Tested in different environments (browser/node)
• Documentation update has been considered

Security

• The security impact of the change has been considered
• Code follows company security practices and guidelines

---

Note

Low Risk
Backward-compatible lint rule extension with default off; only affects OpenAPI validation when users opt in.

Overview
Adds an opt-in disallowDefault option to the operation-2xx-response lint rule. When disallowDefault: true, a default response no longer satisfies the requirement for a successful response—operations must declare an explicit 2xx status code. Default remains false, so existing configs behave the same.

The flag is passed from operation-2xx-response (paths and webhooks) into validateResponseCodes, which only treats default as a 2xx substitute when disallowDefault is off. Docs and a changeset describe configuration and codegen motivation; a unit test covers default-only operations failing when the option is enabled.

^{Reviewed by Cursor Bugbot for commit 7b26dbf. Bugbot is set up for automated code reviews on this repo. Configure here.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 7b26dbf

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@redocly/openapi-core	Minor
@redocly/cli	Minor
@redocly/client-generator	Patch
@redocly/respect-core	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[Copilot]

Pull request overview

Adds an opt-in allowDefault option to the operation-2xx-response rule so teams that rely on code generation can require an explicit 2xx response instead of allowing default to satisfy the rule. The default remains true, preserving current behavior unless configured otherwise.

Changes:

• Added allowDefault?: boolean plumbing through Operation2xxResponse into validateResponseCodes (defaulting to true).
• Updated the validateResponseCodes “default counts as 2xx” clause to be gated by allowDefault.
• Added unit test coverage for allowDefault: false, plus updated rule documentation and a changeset.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
packages/core/src/rules/utils.ts	Gates the default-counts-as-2xx behavior behind the new allowDefault option (default true).
packages/core/src/rules/common/operation-2xx-response.ts	Exposes allowDefault as a rule option and forwards it into shared response-code validation.
packages/core/src/rules/common/tests/operation-2xx-response.test.ts	Adds a unit test asserting default-only responses fail when allowDefault: false.
docs/@v2/rules/oas/operation-2xx-response.md	Documents the new allowDefault option and its motivation/usage.
.changeset/olive-pugs-repeat.md	Publishes the new rule option as a minor change for core + CLI packages.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[AlbinaBlazhko17]

Hi @dimitropoulos! Thanks for the contribution and bringing this up. We will review the PR as soon as possible. To unblock you now, you can get the same check with a custom plugin.
explicit-2xx.mjs::

const ExplicitSuccessResponse = () => {
  return {
    Paths: {
      Responses(responses, { report }) {
        const hasSuccessCode = Object.keys(responses || {}).some((code) =>
          /^2[0-9Xx]{2}$/.test(code)
        );

        if (!hasSuccessCode) {
          report({
            message: 'Operation must define an explicit 2xx response.',
            location: { reportOnKey: true },
          });
        }
      },
    },
  };
};

export default function ExplicitSuccessResponsePlugin() {
  return {
    id: 'codegen',
    rules: {
      oas3: {
        'explicit-2xx-response': ExplicitSuccessResponse,
      },
    },
  };
}

redocly.yaml:

plugins:
  - explicit-2xx.mjs

rules:
  codegen/explicit-2xx-response: error

More about plugins you can find here. I hope it will help you.

[github-actions]

Performance Benchmark (Lower is Faster)

CLI Version	Bundle	Lint	Check Config
cli-latest	▓ 1.00x (Fastest)	▓ 1.00x (Fastest)	▓ 1.00x (Fastest)
cli-next	▓ 1.02x ± 0.03	▓ 1.01x ± 0.02	▓ 1.02x ± 0.02

[AlbinaBlazhko17]

Overall looks good. One question on scope: does a wide-range 2XX response break your generator too, or only default? If 2XX is also a problem for you, requireExplicitStatusCode: true would name the real requirement and cover both. Also, you can use our configurable rules to explicitly add response codes which are supported. More about configurable rules you can find here.

[dimitropoulos]

2XX is totally fine. sorry, wasn't meaning to be crypitc, haha, but the code generator is fern. We do use configurable rules, and actually this PR was spun off of someone adding that, but I said: "no on, let's see if they're interested in upstreaming, the redocly team is really on top of their shit and if it's good to upstream they'll tell us."

and, once I got to doing it I saw that it's a pretty small backwards-compatible change, so I figured it'd be worth having.

if you're happy I'm happy! please merge away

[AlbinaBlazhko17]

Hey @dimitropoulos ! Looks good to me. BTW, have you considered using our SDK generator? The quick overview of the feature you can find there.

[adamaltman]

@dimitropoulos I think the change is good too. Thank you for the suggestion.

We need to add some additional information to our repo to explain we prefer configuration options to have a default value of false. This way everybody can guess the default value of a boolean redocly config value. So I would propose something like disallowDefault: false as the default.

[dimitropoulos]

Hey @dimitropoulos ! Looks good to me. BTW, have you considered using our SDK generator? The quick overview of the feature you can find there.

thanks @adamaltman - no, hadn't heard of it! Looks like it's pretty new (last few days?!). congrats! I will say at first glance the most promising thing to me is that you generate TanStack Query - not just because all things TanStack are obviously amazing, but because it shows you're thinking of your generated outputs in a more general way than just what programming languages to target. There's so much more that can be done with codegen from OpenAPI specs than many of the current top companies are doing, and this is a great example of opening up that line of innovation. nice! we'll definitely keep in on our radar. it helps that literally every interaction with the redocly team has been so pleasant. I'm sure there's not reason not to share that internal to the teams working on this at Cloudflare it's common to hear "well if we have a problem we can just make an issue or PR to the redocly team and more often than not it'll be released by tomorrow evening". you all run a tight ship and it really shows in the quality of the software, but also shows in the way it's all managed. thanks for being so responsive!

[dimitropoulos]

@adamaltman sure no problemo, flipped it in 5b415f2

@JLekawa I saw you added a little addition too (sortof addressing the same thing) so feel free to either drop 5b415f2 and just merge as it was before, or keep it - either way sounds great to me.

[AlbinaBlazhko17]

Thanks @dimitropoulos for the contribution and feedback! The change is released in v2.53.0.