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

[dimitropoulos]

What/Why/How?

Adds allowDefault to operation-2xx-response. Default true, 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

allowDefault: false requires an explicit 2xx.

rules:
  operation-2xx-response:
    severity: error
    allowDefault: false

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 allowDefault: 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
Opt-in lint rule option with backward-compatible default; no auth, data, or runtime behavior changes.

Overview
Adds an opt-in allowDefault option to the operation-2xx-response rule so a default response no longer has to count as a successful 2xx.

Default remains true (previous behavior). With allowDefault: false, operations that only declare default fail the rule, which helps code generators that need an explicit success status for return types. The flag is threaded through validateResponseCodes and only applies to the 2XX range, so operation-4xx-response is unchanged.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 52677b1

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.