Enum SecurityScheme 

#[non_exhaustive]
pub enum SecurityScheme {
    #[non_exhaustive]
    ApiKey {
        name: String,
        location: ParameterIn,
        description: Option<String>,
        deprecated: Option<bool>,
        extensions: Extensions,
    },
    #[non_exhaustive]
    Http {
        scheme: String,
        bearer_format: Option<String>,
        description: Option<String>,
        deprecated: Option<bool>,
        extensions: Extensions,
    },
    #[non_exhaustive]
    MutualTls {
        description: Option<String>,
        deprecated: Option<bool>,
        extensions: Extensions,
    },
    #[non_exhaustive]
    OAuth2 {
        flows: Box<OAuthFlows>,
        oauth2_metadata_url: Option<String>,
        description: Option<String>,
        deprecated: Option<bool>,
        extensions: Extensions,
    },
    #[non_exhaustive]
    OpenIdConnect {
        open_id_connect_url: String,
        description: Option<String>,
        deprecated: Option<bool>,
        extensions: Extensions,
    },
}

A security scheme the API can use.

The variants are the five type values the specification defines. Modelling them as an enum rather than one struct with conditionally-required fields means an unusable combination — an apiKey scheme with OAuth flows, say — cannot be constructed. #[non_exhaustive] because OpenAPI 3.2 adds to this and the addition is #[cfg]-gated. Cargo unifies features across a dependency graph, so any crate enabling openapi32 enables it for every crate in the build – and without this attribute that would turn a downstream exhaustive match into a compile error, which is not what “purely additive” is supposed to mean.

Every variant is sealed too

The attribute above covers a variant being added. 3.2 also adds a field to every variant already here — deprecated, and oauth2MetadataUrl on OAuth2 — so each variant carries the attribute as well. The enum’s does not reach a variant’s field list, and a field list is what a pattern names.

So a pattern takes .., and reads the same in either build:

fn scheme_of(security: &SecurityScheme) -> Option<&str> {
    match security {
        SecurityScheme::Http { scheme, .. } => Some(scheme),
        _ => None,
    }
}

Without it, naming every field is a compile error even when the list is complete for this build — which is the guarantee. It is the error a downstream crate would otherwise have met the day something else in its build turned openapi32 on.

fn scheme_of(security: &SecurityScheme) -> Option<&str> {
    match security {
        SecurityScheme::Http {
            scheme,
            bearer_format,
            description,
            deprecated,
            extensions,
        } => Some(scheme),
        _ => None,
    }
}

Construction goes through the constructors for the same reason: http, bearer, basic, the three api_key_*, mutual_tls, oauth2 and open_id_connect, then with_description, with_extension and the rest.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

#[non_exhaustive]

ApiKey

A key carried in a header, query parameter or cookie.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

name: String

The name of the header, query parameter or cookie.

location: ParameterIn

Where the key is carried. Only query, header and cookie are legal.

description: Option<String>

A description of the scheme. CommonMark syntax may be used.

deprecated: Option<bool>

Whether the scheme is deprecated.

Introduced in OpenAPI 3.2.

extensions: Extensions

Specification extensions.

#[non_exhaustive]

Http

An RFC 7235 Authorization header scheme.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

scheme: String

The registered authorization scheme name, such as bearer.

bearer_format: Option<String>

A hint about the bearer token’s format, such as JWT.

description: Option<String>

A description of the scheme.

deprecated: Option<bool>

Whether the scheme is deprecated.

Introduced in OpenAPI 3.2.

extensions: Extensions

Specification extensions.

#[non_exhaustive]

MutualTls

Mutual TLS client certificate authentication.

Kynos declares this automatically when the listener is configured to verify client certificates, so enabling mTLS cannot leave the description silent about it.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

description: Option<String>

A description of the scheme.

deprecated: Option<bool>

Whether the scheme is deprecated.

Introduced in OpenAPI 3.2.

extensions: Extensions

Specification extensions.

#[non_exhaustive]

OAuth2

OAuth 2.0.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

flows: Box<OAuthFlows>

The supported flows.

oauth2_metadata_url: Option<String>

A URL to the RFC 8414 authorization server metadata.

Introduced in OpenAPI 3.2.

description: Option<String>

A description of the scheme.

deprecated: Option<bool>

Whether the scheme is deprecated.

Introduced in OpenAPI 3.2.

extensions: Extensions

Specification extensions.

#[non_exhaustive]

OpenIdConnect

OpenID Connect Discovery.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

open_id_connect_url: String

The OpenID Connect Discovery URL.

description: Option<String>

A description of the scheme.

deprecated: Option<bool>

Whether the scheme is deprecated.

Introduced in OpenAPI 3.2.

extensions: Extensions

Specification extensions.

Implementations

impl SecurityScheme

pub fn http(scheme: impl Into<String>, bearer_format: Option<String>) -> Self

An HTTP authentication scheme, named by its RFC 7235 scheme token.

bearer and basic are the two worth naming; this is for the rest of the IANA registry, and for a scheme read out of a description someone else wrote.

pub fn bearer(bearer_format: Option<String>) -> Self

An HTTP bearer token scheme.

pub fn basic() -> Self

An HTTP basic authentication scheme.

pub fn api_key_header(name: impl Into<String>) -> Self

An API key carried in a header.

pub fn api_key_query(name: impl Into<String>) -> Self

An API key carried in a query parameter.

pub fn api_key_cookie(name: impl Into<String>) -> Self

An API key carried in a cookie.

pub fn mutual_tls() -> Self

Mutual TLS client certificate authentication.

pub fn oauth2(flows: OAuthFlows) -> Self

OAuth 2.0 with the given flows.

A constructor rather than a struct literal, so the #[cfg]-gated fields are written down once here instead of at every call site — which is what a caller in a crate that cannot see the feature needs.

pub fn open_id_connect(url: impl Into<String>) -> Self

OpenID Connect Discovery, against the given metadata URL.

pub fn with_description(self, description: impl Into<String>) -> Self

Sets the scheme’s description.

pub fn with_extension( self, key: impl Into<String>, value: impl Into<Value>, ) -> Self

Attaches a specification extension.

Every variant is #[non_exhaustive], so a caller outside this crate cannot reach extensions through a struct literal; this is how one arrives. Reading them back needs no method — a pattern with .. still binds the field.

pub fn with_deprecated(self, deprecated: bool) -> Self

States whether the scheme is deprecated.

deprecate is the common case. This exists because deprecated: false is a thing a description can say and a round trip has to keep saying, which a method that only ever writes true cannot express.

Introduced in OpenAPI 3.2, and a blocker for emitting the document as 3.1 — see emit.

pub fn deprecate(self) -> Self

Marks the scheme deprecated.

Introduced in OpenAPI 3.2, and a blocker for emitting the document as 3.1 — see emit.

pub fn with_oauth2_metadata_url(self, url: impl Into<String>) -> Self

Sets the RFC 8414 authorization server metadata URL.

Ignored by any scheme that is not OAuth 2.0, because no other kind has the field. Introduced in OpenAPI 3.2.

Trait Implementations

impl Clone for SecurityScheme

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SecurityScheme

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for SecurityScheme

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for SecurityScheme

impl PartialEq for SecurityScheme

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for SecurityScheme

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for SecurityScheme