Enhancement: ergonomic API for OR security requirements (multiple SecurityRequirement entries)

[kieled]

Problem

OpenAPI security requirements are an OR-list at the operation level:

• security: [ { ApiKey: [] }, { BearerAuth: [] } ] means either ApiKey or BearerAuth

In practice it’s common to support multiple auth mechanisms during migrations (API key OR bearer JWT), or to have alternative schemes.

With aide’s current ergonomics (notably TransformOperation::security_requirement / security_requirement_scopes), it’s easy to accidentally model security as a single requirement object, and it’s not obvious how to express OR cleanly.

Related issues

• How to require multiple securitySchemas? #25 is about requiring multiple schemes in a group / confusion around the schema shape, but this issue is specifically about providing an ergonomic way to express OR across security requirements.

Proposed solution

Add a helper API that makes OR explicit and hard to misuse, e.g.

• op.security_requirement_or(["ApiKey", "BearerAuth"])
• or a lower-level op.security_requirements(vec![SecurityRequirement::from("ApiKey"), SecurityRequirement::from("BearerAuth")])
• or builder helpers on openapi::OpenApi / TransformOperation that mirror the OpenAPI structure.

Expected output (example)

security:
  - ApiKey: []
  - BearerAuth: []

Minimal example use-case

.api_route_with("/v1/foo", get(foo), |op| op, |op| {
    // would like an ergonomic way to express:
    // either API key or bearer token
    op /* .security_requirement_or(["ApiKey", "BearerAuth"]) */
})

Additional context

I searched issues for SecurityRequirement, anyOf security, OR security requirement, etc. and didn’t find a dedicated issue for this ergonomic gap.

[jplatte]

Sorry for the ignorance, this is not something I've interacted with at all. What's the difference to the current security_requirement_multi? Is that for chaining security requirements? What does that look like in the spec?

[kieled]

security_requirement_multi is for AND — it creates a single SecurityRequirement object with multiple schemes (all required together):

# security_requirement_multi(["ApiKey", "BearerAuth"])
security:
  - ApiKey: []
    BearerAuth: []  # AND — both required

OR is expressed by separate entries in the security array:

# .security_requirement("ApiKey").security_requirement("BearerAuth")
security:
  - ApiKey: []
  - BearerAuth: []  # OR — either one works

Chaining .security_requirement("ApiKey").security_requirement("BearerAuth") already produces OR correctly, so this is more of a documentation/discoverability gap than a missing feature. I can submit a PR improving the docs for these methods if that works.

[jplatte]

Thanks for the elaborate response!

If multiple security_requirement calls already do the thing you need, I'd prefer a docs-only change.