Spectral "Operation must define a security requirement" — should OpenAPI default to secure?

Answer

OpenAPI 3.0 does not define a default security posture. If a document has no security section and an operation omits its own security block, the endpoint is effectively public. Therefore, treating the omission as a hard error is an opinionated enforcement of a convention that the spec does not mandate. The safer, more spec‑aligned default is to report the situation as a warning, allowing teams to opt‑in to stricter enforcement if they wish to require explicit security definitions.

Explanation – What Spectral Is Trying to Achieve

• Conventional safety: Many projects adopt a “no security unless declared” policy to avoid accidental exposure. Spectral’s operation-security-defined rule enforces this convention by flagging any operation that lacks an explicit security block when the document has no global security.
• Spec compliance: The OpenAPI spec treats the absence of a security field as a literal lack of security requirements. Tooling such as OpenAPI Generator follows this rule and will generate stubs without authentication middleware when no security is declared.
• No spec‑level default: Currently there is no defaultSecurity field or similar mechanism in the spec to provide a global fallback. Consequently, any default behaviour must be imposed by tooling or by project conventions.

Practical Steps for Your Project

1. Configure Spectral: Keep the rule enabled but set its severity to warning (or info) in .spectral.yaml:

   rules:
     operation-security-defined:
       severity: warning
   

   This will surface the issue without breaking CI or build pipelines.
2. Document the convention: Add a note in your README or design docs that all endpoints must either declare security explicitly or be intentionally public.
3. Optional generator flag: If you use a generator that supports an option like --add-auth, enable it only for projects that require every endpoint to be protected. Document this flag as a non‑spec feature.
4. Verify: Run Spectral on a minimal spec that omits global security and confirm you see warnings for each operation. Then generate a stub (e.g., with OpenAPI Generator for Spring Boot) and check that no security annotations or middleware are present.
5. Upgrade your CI: Treat warnings from Spectral as a gate that can be escalated to errors if the project’s security policy evolves.

Diagnostic Question

To decide whether to shift the rule from warning to error in your own pipeline, ask:

Do you have any intentionally public endpoints, or does the entire API need to be protected by default?

If the answer is “all endpoints must be protected,” you can safely elevate the rule to error and optionally add a generator flag to inject authentication scaffolding.