salvo_oapi/

openapi.rs

//! Rust implementation of OpenAPI Specifications 3.1 and 3.2.

use salvo_core::cfg_feature;

mod callback;
mod components;
mod content;
mod encoding;
mod example;
mod external_docs;
mod header;
pub mod info;
mod link;
pub mod operation;
pub mod parameter;
pub mod path;
pub mod request_body;
pub mod response;
pub mod schema;
pub mod security;
pub mod server;
mod tag;
mod xml;

use std::collections::BTreeSet;
use std::fmt::{self, Debug, Formatter};
use std::sync::LazyLock;

use regex::Regex;
use salvo_core::{Depot, FlowCtrl, Handler, Router, async_trait, writing};
use serde::de::{Error, Expected, Visitor};
use serde::{Deserialize, Deserializer, Serialize, Serializer};

pub use self::callback::Callback;
pub use self::components::Components;
pub use self::content::Content;
pub use self::encoding::Encoding;
pub use self::example::Example;
pub use self::external_docs::ExternalDocs;
pub use self::header::Header;
pub use self::info::{Contact, Info, License};
pub use self::link::Link;
pub use self::operation::{Operation, Operations};
pub use self::parameter::{Parameter, ParameterIn, ParameterStyle, Parameters};
pub use self::path::{PathItem, PathItemType, Paths};
pub use self::request_body::RequestBody;
pub use self::response::{Response, Responses};
pub use self::schema::{
    Array, ArrayItems, BasicType, Discriminator, KnownFormat, Number, Object, Ref, Schema,
    SchemaFormat, SchemaType, Schemas,
};
pub use self::security::{SecurityRequirement, SecurityScheme};
pub use self::server::{Server, ServerVariable, ServerVariables, Servers};
pub use self::tag::Tag;
pub use self::xml::{Xml, XmlNodeType};
use crate::Endpoint;
use crate::routing::{NormNode, OperationSlot};

static PATH_PARAMETER_NAME_REGEX: LazyLock<Regex> =
    LazyLock::new(|| Regex::new(r"\{([^}:]+)").expect("invalid regex"));

/// The structure of the internal storage object paths.
#[cfg(not(feature = "preserve-path-order"))]
pub type PathMap<K, V> = std::collections::BTreeMap<K, V>;
/// The structure of the internal storage object paths.
#[cfg(feature = "preserve-path-order")]
pub type PathMap<K, V> = indexmap::IndexMap<K, V>;

/// The structure of the internal storage object properties.
#[cfg(not(feature = "preserve-prop-order"))]
pub type PropMap<K, V> = std::collections::BTreeMap<K, V>;
/// The structure of the internal storage object properties.
#[cfg(feature = "preserve-prop-order")]
pub type PropMap<K, V> = indexmap::IndexMap<K, V>;

/// Root object of the OpenAPI document.
///
/// You can use [`OpenApi::new`] function to construct a new [`OpenApi`] instance and then
/// use the fields with mutable access to modify them. This is quite tedious if you are not simply
/// just changing one thing thus you can also use the [`OpenApi::new`] to use builder to
/// construct a new [`OpenApi`] object.
///
/// See more details at <https://spec.openapis.org/oas/latest.html#openapi-object>.
#[non_exhaustive]
#[derive(Serialize, Deserialize, Default, Clone, PartialEq, Debug)]
#[serde(rename_all = "camelCase")]
pub struct OpenApi {
    /// OpenAPI document version.
    pub openapi: OpenApiVersion,

    /// URI that identifies this OpenAPI document.
    ///
    /// This field establishes the base URI for relative references when the document is not
    /// retrievable at a stable URL. Added in OpenAPI 3.2.
    ///
    /// See more details at <https://spec.openapis.org/oas/v3.2.0.html#openapi-object>.
    #[serde(rename = "$self", default, skip_serializing_if = "String::is_empty")]
    pub self_uri: String,

    /// Provides metadata about the API.
    ///
    /// See more details at <https://spec.openapis.org/oas/latest.html#info-object>.
    pub info: Info,

    /// List of servers that provides the connectivity information to target servers.
    ///
    /// This is implicitly one server with `url` set to `/`.
    ///
    /// See more details at <https://spec.openapis.org/oas/latest.html#server-object>.
    #[serde(default, skip_serializing_if = "BTreeSet::is_empty")]
    pub servers: BTreeSet<Server>,

    /// Available paths and operations for the API.
    ///
    /// See more details at <https://spec.openapis.org/oas/latest.html#paths-object>.
    pub paths: Paths,

    /// Incoming webhooks that may be received as part of this API.
    ///
    /// Each value is a [`PathItem`] (or a [`Ref`] to one) keyed by a unique name. Added in
    /// OpenAPI 3.1.
    ///
    /// See more details at <https://spec.openapis.org/oas/v3.1.0#openapi-object>.
    #[serde(skip_serializing_if = "PathMap::is_empty", default)]
    pub webhooks: PathMap<String, RefOr<PathItem>>,

    /// Holds various reusable schemas for the OpenAPI document.
    ///
    /// Few of these elements are security schemas and object schemas.
    ///
    /// See more details at <https://spec.openapis.org/oas/latest.html#components-object>.
    #[serde(default, skip_serializing_if = "Components::is_empty")]
    pub components: Components,

    /// Declaration of global security mechanisms that can be used across the API. The individual
    /// operations can override the declarations. You can use `SecurityRequirement::default()`
    /// if you wish to make security optional by adding it to the list of securities.
    ///
    /// See more details at <https://spec.openapis.org/oas/latest.html#security-requirement-object>.
    #[serde(default, skip_serializing_if = "BTreeSet::is_empty")]
    pub security: BTreeSet<SecurityRequirement>,

    /// List of tags can be used to add additional documentation to matching tags of operations.
    ///
    /// See more details at <https://spec.openapis.org/oas/latest.html#tag-object>.
    #[serde(default, skip_serializing_if = "BTreeSet::is_empty")]
    pub tags: BTreeSet<Tag>,

    /// Global additional documentation reference.
    ///
    /// See more details at <https://spec.openapis.org/oas/latest.html#external-documentation-object>.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub external_docs: Option<ExternalDocs>,

    /// The default value for the `$schema` keyword within Schema Objects contained in this
    /// document. It defaults to `<https://spec.openapis.org/oas/3.1/dialect/base>` and, when
    /// set, must be a URI.
    ///
    /// See <https://spec.openapis.org/oas/v3.1.0#openapi-object> for details.
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub json_schema_dialect: String,

    /// Optional extensions "x-something".
    #[serde(skip_serializing_if = "PropMap::is_empty", flatten)]
    pub extensions: PropMap<String, serde_json::Value>,
}

impl OpenApi {
    /// Construct a new [`OpenApi`] object.
    ///
    /// # Examples
    ///
    /// ```
    /// # use salvo_oapi::{Info, Paths, OpenApi};
    /// #
    /// let openapi = OpenApi::new("pet api", "0.1.0");
    /// ```
    pub fn new(title: impl Into<String>, version: impl Into<String>) -> Self {
        Self {
            info: Info::new(title, version),
            ..Default::default()
        }
    }
    /// Construct a new [`OpenApi`] object.
    ///
    /// Function accepts [`Info`] metadata of the API;
    ///
    /// # Examples
    ///
    /// ```
    /// # use salvo_oapi::{Info, Paths, OpenApi};
    /// #
    /// let openapi = OpenApi::new("pet api", "0.1.0");
    /// ```
    #[must_use]
    pub fn with_info(info: Info) -> Self {
        Self {
            info,
            ..Default::default()
        }
    }

    /// Set the OpenAPI Specification version used by this document.
    ///
    /// New documents default to OpenAPI 3.1. Use this method to opt in to OpenAPI 3.2.
    ///
    /// # Version-aware generation
    ///
    /// [`OpenApi::merge_router`] only emits constructs the declared version supports: `QUERY`
    /// routes and custom HTTP methods (which need the 3.2 `query` field and
    /// `additionalOperations` respectively) are skipped with a warning while the document
    /// declares 3.1.
    ///
    /// Fields you set by hand are *not* validated against the declared version — building a
    /// [`Tag`] with `kind` and leaving the document at 3.1 produces a 3.1 document carrying a
    /// 3.2 field. Set the version first.
    ///
    /// # Documentation UI support
    ///
    /// All four bundled UIs load a 3.2 document, but their support for the new `query`
    /// operation differs. As of Swagger UI v5.32.11 (vendored in this crate) `query` operations
    /// render correctly; Scalar, RapiDoc and ReDoc — which load from a CDN at runtime — display
    /// the rest of the document but omit `query` operations.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use salvo_oapi::{OpenApi, OpenApiVersion};
    /// let openapi = OpenApi::new("pet api", "0.1.0").openapi_version(OpenApiVersion::Version3_2);
    /// assert_eq!(openapi.openapi, OpenApiVersion::Version3_2);
    /// ```
    #[must_use]
    pub fn openapi_version(mut self, version: OpenApiVersion) -> Self {
        self.openapi = version;
        self
    }

    /// Set the URI that identifies this OpenAPI document.
    ///
    /// This serializes as the OpenAPI 3.2 `$self` field. Set the document version to
    /// [`OpenApiVersion::Version3_2`] when using it.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use salvo_oapi::{OpenApi, OpenApiVersion};
    /// let openapi = OpenApi::new("pet api", "0.1.0")
    ///     .openapi_version(OpenApiVersion::Version3_2)
    ///     .self_uri("https://example.com/openapi.json");
    /// assert_eq!(openapi.self_uri, "https://example.com/openapi.json");
    /// ```
    #[must_use]
    pub fn self_uri(mut self, self_uri: impl Into<String>) -> Self {
        self.self_uri = self_uri.into();
        self
    }

    /// Converts this [`OpenApi`] to JSON String. This method essentially calls
    /// [`serde_json::to_string`] method.
    pub fn to_json(&self) -> Result<String, serde_json::Error> {
        serde_json::to_string(self)
    }

    /// Converts this [`OpenApi`] to pretty JSON String. This method essentially calls
    /// [`serde_json::to_string_pretty`] method.
    pub fn to_pretty_json(&self) -> Result<String, serde_json::Error> {
        serde_json::to_string_pretty(self)
    }

    cfg_feature! {
        #![feature ="yaml"]
        /// Converts this [`OpenApi`] to YAML String. This method essentially calls [`serde_norway::to_string`] method.
        pub fn to_yaml(&self) -> Result<String, serde_norway::Error> {
            serde_norway::to_string(self)
        }
    }

    /// Merge `other` [`OpenApi`] consuming it and resuming its content.
    ///
    /// Merge function will take all `self` nonexistent _`servers`, `paths`, `webhooks`,
    /// `schemas`, `responses`, `security_schemes`, `security_requirements` and `tags`_ from
    /// _`other`_ [`OpenApi`].
    ///
    /// This function performs a shallow comparison for `paths`, `webhooks`, `schemas`,
    /// `responses` and `security schemes` which means that only _`name`_ and _`path`_ is used
    /// for comparison. When a match occurs the existing item will be overwritten.
    ///
    /// For _`servers`_, _`tags`_ and _`security_requirements`_ the whole item will be used for
    /// comparison.
    ///
    /// **Note!** `info`, `openapi`, `self_uri`, `external_docs` and `json_schema_dialect` will not
    /// be merged.
    #[must_use]
    pub fn merge(mut self, mut other: Self) -> Self {
        self.servers.append(&mut other.servers);
        self.paths.append(&mut other.paths);
        for (name, item) in std::mem::take(&mut other.webhooks) {
            self.webhooks.insert(name, item);
        }
        self.components.append(&mut other.components);
        self.security.append(&mut other.security);
        self.tags.append(&mut other.tags);
        self
    }

    /// Nest another [`OpenApi`] document under the given path prefix.
    ///
    /// All paths from `other` will be prefixed with `path` and then merged into `self`.
    /// Components, security, tags, and servers are merged as in [`OpenApi::merge`].
    ///
    /// # Examples
    ///
    /// ```
    /// # use salvo_oapi::OpenApi;
    /// let api = OpenApi::new("My Api", "1.0.0");
    /// let user_api = OpenApi::new("User Api", "1.0.0");
    /// let nested = api.nest("/api/v1", user_api);
    /// ```
    #[must_use]
    pub fn nest<P: Into<String>>(self, path: P, other: Self) -> Self {
        self.nest_with_path_composer(path, other, |base, item_path| {
            format!(
                "{}/{}",
                base.trim_end_matches('/'),
                item_path.trim_start_matches('/')
            )
        })
    }

    /// Nest another [`OpenApi`] document with a custom path composer.
    ///
    /// In most cases you should use [`OpenApi::nest`] instead.
    /// Only use this method if you need custom path composition for a specific use case.
    ///
    /// `composer` is a function that takes two strings, the base path and the path to nest,
    /// and returns the composed path for the API Specification.
    #[must_use]
    pub fn nest_with_path_composer<P: Into<String>, F: Fn(&str, &str) -> String>(
        mut self,
        path: P,
        mut other: Self,
        composer: F,
    ) -> Self {
        let path: String = path.into();

        // Take paths out of other, prefix them, and insert into self
        let other_paths = std::mem::take(&mut other.paths);
        for (item_path, item) in other_paths.iter() {
            let composed = composer(&path, item_path);
            self.paths.insert(composed, item.clone());
        }

        // Merge the remaining parts (servers, components, security, tags)
        // Paths in other are already empty so merge won't duplicate them
        self.merge(other)
    }

    /// Add [`Info`] metadata of the API.
    #[must_use]
    pub fn info<I: Into<Info>>(mut self, info: I) -> Self {
        self.info = info.into();
        self
    }

    /// Add iterator of [`Server`]s to configure target servers.
    #[must_use]
    pub fn servers<S: IntoIterator<Item = Server>>(mut self, servers: S) -> Self {
        self.servers = servers.into_iter().collect();
        self
    }
    /// Add [`Server`] to configure operations and endpoints of the API and returns `Self`.
    #[must_use]
    pub fn add_server<S>(mut self, server: S) -> Self
    where
        S: Into<Server>,
    {
        self.servers.insert(server.into());
        self
    }

    /// Set paths to configure operations and endpoints of the API.
    #[must_use]
    pub fn paths<P: Into<Paths>>(mut self, paths: P) -> Self {
        self.paths = paths.into();
        self
    }
    /// Add [`PathItem`] to configure operations and endpoints of the API and returns `Self`.
    #[must_use]
    pub fn add_path<P, I>(mut self, path: P, item: I) -> Self
    where
        P: Into<String>,
        I: Into<PathItem>,
    {
        self.paths.insert(path.into(), item.into());
        self
    }

    /// Replace the incoming webhooks map and return `Self`.
    ///
    /// Webhooks were added in OpenAPI 3.1. See [`OpenApi::webhooks`].
    #[must_use]
    pub fn webhooks<I, K, V>(mut self, webhooks: I) -> Self
    where
        I: IntoIterator<Item = (K, V)>,
        K: Into<String>,
        V: Into<RefOr<PathItem>>,
    {
        self.webhooks = webhooks
            .into_iter()
            .map(|(name, item)| (name.into(), item.into()))
            .collect();
        self
    }

    /// Insert a single named webhook and return `Self`.
    ///
    /// The value may be an inline [`PathItem`] or a [`Ref`] to one stored elsewhere.
    #[must_use]
    pub fn add_webhook<K: Into<String>, V: Into<RefOr<PathItem>>>(
        mut self,
        name: K,
        webhook: V,
    ) -> Self {
        self.webhooks.insert(name.into(), webhook.into());
        self
    }

    /// Add [`Components`] to configure reusable schemas.
    #[must_use]
    pub fn components(mut self, components: impl Into<Components>) -> Self {
        self.components = components.into();
        self
    }

    /// Add iterator of [`SecurityRequirement`]s that are globally available for all operations.
    #[must_use]
    pub fn security<S: IntoIterator<Item = SecurityRequirement>>(mut self, security: S) -> Self {
        self.security = security.into_iter().collect();
        self
    }

    /// Add [`SecurityScheme`] to [`Components`] and returns `Self`.
    ///
    /// Accepts two arguments where first is the name of the [`SecurityScheme`]. This is later when
    /// referenced by [`SecurityRequirement`][requirement]s. Second parameter is the
    /// [`SecurityScheme`].
    ///
    /// [requirement]: crate::SecurityRequirement
    #[must_use]
    pub fn add_security_scheme<N: Into<String>, S: Into<SecurityScheme>>(
        mut self,
        name: N,
        security_scheme: S,
    ) -> Self {
        self.components
            .security_schemes
            .insert(name.into(), security_scheme.into());

        self
    }

    /// Add iterator of [`SecurityScheme`]s to [`Components`].
    ///
    /// Accepts two arguments where first is the name of the [`SecurityScheme`]. This is later when
    /// referenced by [`SecurityRequirement`][requirement]s. Second parameter is the
    /// [`SecurityScheme`].
    ///
    /// [requirement]: crate::SecurityRequirement
    #[must_use]
    pub fn extend_security_schemes<
        I: IntoIterator<Item = (N, S)>,
        N: Into<String>,
        S: Into<SecurityScheme>,
    >(
        mut self,
        schemas: I,
    ) -> Self {
        self.components.security_schemes.extend(
            schemas
                .into_iter()
                .map(|(name, item)| (name.into(), item.into())),
        );
        self
    }

    /// Add [`Schema`] to [`Components`] and returns `Self`.
    ///
    /// Accepts two arguments where first is name of the schema and second is the schema itself.
    #[must_use]
    pub fn add_schema<S: Into<String>, I: Into<RefOr<Schema>>>(
        mut self,
        name: S,
        schema: I,
    ) -> Self {
        self.components.schemas.insert(name, schema);
        self
    }

    /// Add [`Schema`]s from iterator.
    ///
    /// # Examples
    /// ```
    /// # use salvo_oapi::{OpenApi, Object, BasicType, Schema};
    /// OpenApi::new("api", "0.0.1").extend_schemas([(
    ///     "Pet",
    ///     Schema::from(
    ///         Object::new()
    ///             .property("name", Object::new().schema_type(BasicType::String))
    ///             .required("name"),
    ///     ),
    /// )]);
    /// ```
    #[must_use]
    pub fn extend_schemas<I, C, S>(mut self, schemas: I) -> Self
    where
        I: IntoIterator<Item = (S, C)>,
        C: Into<RefOr<Schema>>,
        S: Into<String>,
    {
        self.components.schemas.extend(
            schemas
                .into_iter()
                .map(|(name, schema)| (name.into(), schema.into())),
        );
        self
    }

    /// Add a new response and returns `self`.
    #[must_use]
    pub fn response<S: Into<String>, R: Into<RefOr<Response>>>(
        mut self,
        name: S,
        response: R,
    ) -> Self {
        self.components
            .responses
            .insert(name.into(), response.into());
        self
    }

    /// Extends responses with the contents of an iterator.
    #[must_use]
    pub fn extend_responses<
        I: IntoIterator<Item = (S, R)>,
        S: Into<String>,
        R: Into<RefOr<Response>>,
    >(
        mut self,
        responses: I,
    ) -> Self {
        self.components.responses.extend(
            responses
                .into_iter()
                .map(|(name, response)| (name.into(), response.into())),
        );
        self
    }

    /// Add iterator of [`Tag`]s to add additional documentation for **operations** tags.
    #[must_use]
    pub fn tags<I, T>(mut self, tags: I) -> Self
    where
        I: IntoIterator<Item = T>,
        T: Into<Tag>,
    {
        self.tags = tags.into_iter().map(Into::into).collect();
        self
    }

    /// Add [`ExternalDocs`] for referring additional documentation.
    #[must_use]
    pub fn external_docs(mut self, external_docs: ExternalDocs) -> Self {
        self.external_docs = Some(external_docs);
        self
    }

    /// Override the default JSON Schema dialect for this OpenAPI document.
    ///
    /// Sets the [`jsonSchemaDialect`][spec] top-level field, which provides the default
    /// `$schema` value used by Schema Objects contained in this document.
    ///
    /// [spec]: https://spec.openapis.org/oas/v3.1.0#openapi-object
    ///
    /// # Examples
    ///
    /// _**Override default schema dialect.**_
    /// ```rust
    /// # use salvo_oapi::OpenApi;
    /// let _ = OpenApi::new("openapi", "0.1.0")
    ///     .json_schema_dialect("http://json-schema.org/draft-07/schema#");
    /// ```
    #[must_use]
    pub fn json_schema_dialect<S: Into<String>>(mut self, dialect: S) -> Self {
        self.json_schema_dialect = dialect.into();
        self
    }

    /// Add openapi extension (`x-something`) for [`OpenApi`].
    #[must_use]
    pub fn add_extension<K: Into<String>>(mut self, key: K, value: serde_json::Value) -> Self {
        self.extensions.insert(key.into(), value);
        self
    }

    /// Consumes the [`OpenApi`] and returns [`Router`] with the [`OpenApi`] as handler.
    pub fn into_router(self, path: impl Into<String>) -> Router {
        Router::with_path(path.into()).goal(self)
    }

    /// Consumes the [`OpenApi`] and information from a [`Router`].
    #[must_use]
    pub fn merge_router(self, router: &Router) -> Self {
        self.merge_router_with_base(router, "/")
    }

    /// Consumes the [`OpenApi`] and information from a [`Router`] with base path.
    #[must_use]
    pub fn merge_router_with_base(mut self, router: &Router, base: impl AsRef<str>) -> Self {
        let mut node = NormNode::new(router, Default::default());
        self.merge_norm_node(&mut node, base.as_ref());
        self
    }

    fn merge_norm_node(&mut self, node: &mut NormNode, base_path: &str) {
        fn join_path(a: &str, b: &str) -> String {
            if a.is_empty() {
                b.to_owned()
            } else if b.is_empty() {
                a.to_owned()
            } else {
                format!("{}/{}", a.trim_end_matches('/'), b.trim_start_matches('/'))
            }
        }

        let path = join_path(base_path, node.path.as_deref().unwrap_or_default());
        let path_parameter_names = PATH_PARAMETER_NAME_REGEX
            .captures_iter(&path)
            .filter_map(|captures| {
                captures
                    .iter()
                    .skip(1)
                    .map(|capture| {
                        capture
                            .expect("regex captures should not be None")
                            .as_str()
                            .to_owned()
                    })
                    .next()
            })
            .collect::<Vec<_>>();

        if let Some(handler_type_id) = &node.handler_type_id
            && let Some(creator) = crate::EndpointRegistry::find(handler_type_id)
        {
            // `query` operations and `additionalOperations` were both added in OpenAPI 3.2.
            // Emitting either into a document that still declares 3.1 would make it invalid,
            // so drop the slot and tell the user how to opt in.
            let slot = node.method.clone().filter(|slot| {
                let requires_3_2 = match slot {
                    OperationSlot::Standard(PathItemType::Query) => Some("QUERY"),
                    OperationSlot::Additional(method) => Some(&**method),
                    OperationSlot::Standard(_) => None,
                };
                match requires_3_2 {
                    Some(method) if self.openapi == OpenApiVersion::Version3_1 => {
                        tracing::warn!(
                            path,
                            method,
                            handler_name = node.handler_type_name,
                            "HTTP method has no OpenAPI 3.1 representation; skipping in the \
                             generated document. Call `OpenApi::openapi_version` with \
                             `OpenApiVersion::Version3_2` to emit it"
                        );
                        false
                    }
                    _ => true,
                }
            });

            if let Some(slot) = slot {
                let Endpoint {
                    mut operation,
                    mut components,
                } = creator();
                operation.tags.extend(node.metadata.tags.iter().cloned());
                operation
                    .securities
                    .extend(node.metadata.securities.iter().cloned());
                let not_exist_parameters = operation
                    .parameters
                    .0
                    .iter()
                    .filter(|p| {
                        p.parameter_in == ParameterIn::Path
                            && !path_parameter_names.contains(&p.name)
                    })
                    .map(|p| &p.name)
                    .collect::<Vec<_>>();
                if !not_exist_parameters.is_empty() {
                    tracing::warn!(parameters = ?not_exist_parameters, path, handler_name = node.handler_type_name, "information for not exist parameters");
                }
                #[cfg(debug_assertions)]
                {
                    let meta_not_exist_parameters = path_parameter_names
                        .iter()
                        .filter(|name| {
                            !name.starts_with('*')
                                && !operation.parameters.0.iter().any(|parameter| {
                                    parameter.name == **name
                                        && parameter.parameter_in == ParameterIn::Path
                                })
                        })
                        .collect::<Vec<_>>();

                    if !meta_not_exist_parameters.is_empty() {
                        tracing::warn!(parameters = ?meta_not_exist_parameters, path, handler_name = node.handler_type_name, "parameters information not provided");
                    }
                }
                let path_item = self.paths.entry(path.clone()).or_default();
                let occupied = match &slot {
                    OperationSlot::Standard(method) => path_item.operations.contains_key(method),
                    OperationSlot::Additional(method) => {
                        path_item.additional_operations.contains_key(method)
                    }
                };
                if occupied {
                    tracing::warn!(
                        "path `{}` already contains operation for method `{:?}`",
                        path,
                        slot
                    );
                } else {
                    match slot {
                        OperationSlot::Standard(method) => {
                            path_item.operations.insert(method, operation);
                        }
                        OperationSlot::Additional(method) => {
                            path_item.additional_operations.insert(method, operation);
                        }
                    }
                }
                self.components.append(&mut components);
            } else if node.method.is_none() {
                // No method filter on this route: OpenAPI has no "any-method"
                // operation slot, so attaching the same handler to GET/POST/PUT/PATCH
                // would lie about the API. Skip and warn so the user can attach a
                // method filter (`.get(handler)`, `.post(handler)`, ...) explicitly.
                tracing::warn!(
                    path,
                    handler_name = node.handler_type_name,
                    "endpoint has no HTTP method filter; skipping in OpenAPI document. \
                     Add `.get()`, `.post()`, etc. to the router to include it"
                );
            }
        }

        for child in &mut node.children {
            self.merge_norm_node(child, &path);
        }
    }
}

#[async_trait]
impl Handler for OpenApi {
    async fn handle(
        &self,
        req: &mut salvo_core::Request,
        _depot: &mut Depot,
        res: &mut salvo_core::Response,
        _ctrl: &mut FlowCtrl,
    ) {
        let pretty = req
            .queries()
            .get("pretty")
            .map(|v| &**v != "false")
            .unwrap_or(false);
        let content = if pretty {
            self.to_pretty_json().unwrap_or_default()
        } else {
            self.to_json().unwrap_or_default()
        };
        res.render(writing::Text::Json(&content));
    }
}
/// Represents available [OpenAPI versions][version].
///
/// [version]: <https://spec.openapis.org/oas/latest.html#versions>
#[derive(Serialize, Clone, PartialEq, Eq, Default, Debug)]
pub enum OpenApiVersion {
    /// Serializes to `3.1.0` and remains the default for backward compatibility.
    #[serde(rename = "3.1.0")]
    #[default]
    Version3_1,
    /// Serializes to `3.2.0`.
    #[serde(rename = "3.2.0")]
    Version3_2,
}

impl<'de> Deserialize<'de> for OpenApiVersion {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        struct VersionVisitor;

        impl Visitor<'_> for VersionVisitor {
            type Value = OpenApiVersion;

            fn expecting(&self, formatter: &mut Formatter) -> fmt::Result {
                formatter.write_str("a version string in 3.1.x or 3.2.x format")
            }

            fn visit_str<E>(self, v: &str) -> Result<Self::Value, E>
            where
                E: Error,
            {
                self.visit_string(v.to_owned())
            }

            fn visit_string<E>(self, v: String) -> Result<Self::Value, E>
            where
                E: Error,
            {
                let mut digits = v.split('.').map(|digit| digit.parse::<u32>());
                let version = match (digits.next(), digits.next(), digits.next(), digits.next()) {
                    (Some(Ok(3)), Some(Ok(minor)), Some(Ok(_)), None) => minor,
                    _ => {
                        let expected: &dyn Expected = &"3.1.x or 3.2.x";
                        return Err(Error::invalid_value(
                            serde::de::Unexpected::Str(&v),
                            expected,
                        ));
                    }
                };

                match version {
                    1 => Ok(OpenApiVersion::Version3_1),
                    2 => Ok(OpenApiVersion::Version3_2),
                    _ => {
                        let expected: &dyn Expected = &"3.1.x or 3.2.x";
                        Err(Error::invalid_value(
                            serde::de::Unexpected::Str(&v),
                            expected,
                        ))
                    }
                }
            }
        }

        deserializer.deserialize_string(VersionVisitor)
    }
}

/// Value used to indicate whether reusable schema, parameter or operation is deprecated.
///
/// The value will serialize to boolean.
#[derive(PartialEq, Eq, Clone, Debug)]
pub enum Deprecated {
    /// Is deprecated.
    True,
    /// Is not deprecated.
    False,
}
impl From<bool> for Deprecated {
    fn from(b: bool) -> Self {
        if b { Self::True } else { Self::False }
    }
}

impl Serialize for Deprecated {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        serializer.serialize_bool(matches!(self, Self::True))
    }
}

impl<'de> Deserialize<'de> for Deprecated {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        struct BoolVisitor;
        impl Visitor<'_> for BoolVisitor {
            type Value = Deprecated;

            fn expecting(&self, formatter: &mut Formatter) -> fmt::Result {
                formatter.write_str("a bool true or false")
            }

            fn visit_bool<E>(self, v: bool) -> Result<Self::Value, E>
            where
                E: serde::de::Error,
            {
                match v {
                    true => Ok(Deprecated::True),
                    false => Ok(Deprecated::False),
                }
            }
        }
        deserializer.deserialize_bool(BoolVisitor)
    }
}

/// Value used to indicate whether parameter or property is required.
///
/// The value will serialize to boolean.
#[derive(PartialEq, Eq, Default, Clone, Debug)]
pub enum Required {
    /// Is required.
    True,
    /// Is not required.
    False,
    /// This value is not set, it will treat as `False` when serialize to boolean.
    #[default]
    Unset,
}

impl From<bool> for Required {
    fn from(value: bool) -> Self {
        if value { Self::True } else { Self::False }
    }
}

impl Serialize for Required {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        serializer.serialize_bool(matches!(self, Self::True))
    }
}

impl<'de> Deserialize<'de> for Required {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        struct BoolVisitor;
        impl Visitor<'_> for BoolVisitor {
            type Value = Required;

            fn expecting(&self, formatter: &mut Formatter) -> fmt::Result {
                formatter.write_str("a bool true or false")
            }

            fn visit_bool<E>(self, v: bool) -> Result<Self::Value, E>
            where
                E: serde::de::Error,
            {
                match v {
                    true => Ok(Required::True),
                    false => Ok(Required::False),
                }
            }
        }
        deserializer.deserialize_bool(BoolVisitor)
    }
}

/// A [`Ref`] or some other type `T`.
///
/// Typically used in combination with [`Components`] and is an union type between [`Ref`] and any
/// other given type such as [`Schema`] or [`Response`].
#[derive(Serialize, Deserialize, Clone, PartialEq, Eq, Debug)]
#[serde(untagged)]
pub enum RefOr<T> {
    /// A [`Ref`] to a reusable component.
    Ref(schema::Ref),
    /// Some other type `T`.
    Type(T),
}

#[cfg(test)]
mod tests {
    use std::fmt::Debug;
    use std::str::FromStr;

    use bytes::Bytes;
    use salvo_core::http::ResBody;
    use salvo_core::prelude::*;
    use serde_json::{Value, json};

    use super::response::Response;
    use super::*;
    use crate::ToSchema;
    use crate::extract::*;
    use crate::security::{ApiKey, ApiKeyValue, Http, HttpAuthScheme};
    use crate::server::Server;

    #[test]
    fn serialize_deserialize_openapi_version_success() -> Result<(), serde_json::Error> {
        assert_eq!(serde_json::to_value(&OpenApiVersion::Version3_1)?, "3.1.0");
        assert_eq!(serde_json::to_value(&OpenApiVersion::Version3_2)?, "3.2.0");
        assert_eq!(
            serde_json::from_str::<OpenApiVersion>(r#""3.1.9""#)?,
            OpenApiVersion::Version3_1
        );
        assert_eq!(
            serde_json::from_str::<OpenApiVersion>(r#""3.2.7""#)?,
            OpenApiVersion::Version3_2
        );
        Ok(())
    }

    #[test]
    fn deserialize_openapi_version_rejects_unsupported_or_malformed_versions() {
        for version in ["3.0.4", "3.3.0", "3.2", "3.2.x", "4.0.0"] {
            assert!(
                serde_json::from_value::<OpenApiVersion>(version.into()).is_err(),
                "expected {version} to be rejected"
            );
        }
    }

    #[test]
    fn openapi_3_2_baseline_fields_serialize_and_deserialize() -> Result<(), serde_json::Error> {
        let doc = OpenApi::new("pet api", "0.1.0")
            .openapi_version(OpenApiVersion::Version3_2)
            .self_uri("https://example.com/openapi.json");

        let value = serde_json::to_value(&doc)?;
        assert_eq!(value["openapi"], "3.2.0");
        assert_eq!(value["$self"], "https://example.com/openapi.json");

        let deserialized: OpenApi = serde_json::from_value(json!({
            "openapi": "3.2.4",
            "$self": "https://example.com/openapi.json",
            "info": {
                "title": "pet api",
                "version": "0.1.0"
            },
            "servers": [],
            "paths": {},
            "components": {},
            "security": [],
            "tags": []
        }))?;
        assert_eq!(deserialized.openapi, OpenApiVersion::Version3_2);
        assert_eq!(deserialized.self_uri, "https://example.com/openapi.json");
        Ok(())
    }

    #[test]
    fn openapi_defaults_to_3_1_and_omits_empty_self_uri() -> Result<(), serde_json::Error> {
        let value = serde_json::to_value(OpenApi::new("pet api", "0.1.0"))?;

        assert_eq!(value["openapi"], "3.1.0");
        assert!(value.get("$self").is_none());
        Ok(())
    }

    #[test]
    fn serialize_openapi_json_minimal_success() -> Result<(), serde_json::Error> {
        let raw_json = r#"{
            "openapi": "3.1.0",
            "info": {
              "title": "My api",
              "description": "My api description",
              "license": {
                "name": "MIT",
                "url": "http://mit.licence"
              },
              "version": "1.0.0",
              "contact": {},
              "termsOfService": "terms of service"
            },
            "paths": {}
          }"#;
        let doc: OpenApi = OpenApi::with_info(
            Info::default()
                .description("My api description")
                .license(License::new("MIT").url("http://mit.licence"))
                .title("My api")
                .version("1.0.0")
                .terms_of_service("terms of service")
                .contact(Contact::default()),
        );
        let serialized = doc.to_json()?;

        assert_eq!(
            Value::from_str(&serialized)?,
            Value::from_str(raw_json)?,
            "expected serialized json to match raw: \nserialized: \n{serialized} \nraw: \n{raw_json}"
        );
        Ok(())
    }

    #[test]
    fn serialize_openapi_json_with_paths_success() -> Result<(), serde_json::Error> {
        let doc = OpenApi::new("My big api", "1.1.0").paths(
            Paths::new()
                .path(
                    "/api/v1/users",
                    PathItem::new(
                        PathItemType::Get,
                        Operation::new().add_response("200", Response::new("Get users list")),
                    ),
                )
                .path(
                    "/api/v1/users",
                    PathItem::new(
                        PathItemType::Post,
                        Operation::new().add_response("200", Response::new("Post new user")),
                    ),
                )
                .path(
                    "/api/v1/users/{id}",
                    PathItem::new(
                        PathItemType::Get,
                        Operation::new().add_response("200", Response::new("Get user by id")),
                    ),
                ),
        );

        let serialized = doc.to_json()?;
        let expected = r#"
        {
            "openapi": "3.1.0",
            "info": {
              "title": "My big api",
              "version": "1.1.0"
            },
            "paths": {
              "/api/v1/users": {
                "get": {
                  "responses": {
                    "200": {
                      "description": "Get users list"
                    }
                  }
                },
                "post": {
                  "responses": {
                    "200": {
                      "description": "Post new user"
                    }
                  }
                }
              },
              "/api/v1/users/{id}": {
                "get": {
                  "responses": {
                    "200": {
                      "description": "Get user by id"
                    }
                  }
                }
              }
            }
          }
        "#
        .replace("\r\n", "\n");

        assert_eq!(
            Value::from_str(&serialized)?,
            Value::from_str(&expected)?,
            "expected serialized json to match raw: \nserialized: \n{serialized} \nraw: \n{expected}"
        );
        Ok(())
    }

    #[test]
    fn merge_2_openapi_documents() {
        let mut api_1 = OpenApi::new("Api", "v1").paths(Paths::new().path(
            "/api/v1/user",
            PathItem::new(
                PathItemType::Get,
                Operation::new().add_response("200", Response::new("This will not get added")),
            ),
        ));

        let api_2 = OpenApi::new("Api", "v2")
            .paths(
                Paths::new()
                    .path(
                        "/api/v1/user",
                        PathItem::new(
                            PathItemType::Get,
                            Operation::new().add_response("200", Response::new("Get user success")),
                        ),
                    )
                    .path(
                        "/ap/v2/user",
                        PathItem::new(
                            PathItemType::Get,
                            Operation::new()
                                .add_response("200", Response::new("Get user success 2")),
                        ),
                    )
                    .path(
                        "/api/v2/user",
                        PathItem::new(
                            PathItemType::Post,
                            Operation::new().add_response("200", Response::new("Get user success")),
                        ),
                    ),
            )
            .components(
                Components::new().add_schema(
                    "User2",
                    Object::new()
                        .schema_type(BasicType::Object)
                        .property("name", Object::new().schema_type(BasicType::String)),
                ),
            );

        api_1 = api_1.merge(api_2);
        let value = serde_json::to_value(&api_1).unwrap();

        assert_eq!(
            value,
            json!(
                {
                  "openapi": "3.1.0",
                  "info": {
                    "title": "Api",
                    "version": "v1"
                  },
                  "paths": {
                    "/ap/v2/user": {
                      "get": {
                        "responses": {
                          "200": {
                            "description": "Get user success 2"
                          }
                        }
                      }
                    },
                    "/api/v1/user": {
                      "get": {
                        "responses": {
                          "200": {
                            "description": "Get user success"
                          }
                        }
                      }
                    },
                    "/api/v2/user": {
                      "post": {
                        "responses": {
                          "200": {
                            "description": "Get user success"
                          }
                        }
                      }
                    }
                  },
                  "components": {
                    "schemas": {
                      "User2": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
            )
        )
    }

    #[test]
    fn test_simple_document_with_security() {
        #[derive(Deserialize, Serialize, ToSchema)]
        #[salvo(schema(examples(json!({"name": "bob the cat", "id": 1}))))]
        struct Pet {
            id: u64,
            name: String,
            age: Option<i32>,
        }

        /// Get pet by id
        ///
        /// Get pet from database by pet database id
        #[salvo_oapi::endpoint(
            responses(
                (status_code = 200, description = "Pet found successfully"),
                (status_code = 404, description = "Pet was not found")
            ),
            parameters(
                ("id", description = "Pet database id to get Pet for"),
            ),
            security(
                (),
                ("my_auth" = ["read:items", "edit:items"]),
                ("token_jwt" = []),
                ("api_key1" = [], "api_key2" = []),
            )
        )]
        pub async fn get_pet_by_id(pet_id: PathParam<u64>) -> Json<Pet> {
            let pet = Pet {
                id: pet_id.into_inner(),
                age: None,
                name: "lightning".to_owned(),
            };
            Json(pet)
        }

        let mut doc = salvo_oapi::OpenApi::new("my application", "0.1.0").add_server(
            Server::new("/api/bar/")
                .description("this is description of the server")
                .add_variable(
                    "username",
                    ServerVariable::new()
                        .default_value("the_user")
                        .description("this is user"),
                ),
        );
        doc.components.security_schemes.insert(
            "token_jwt".into(),
            SecurityScheme::Http(Http::new(HttpAuthScheme::Bearer).bearer_format("JWT")),
        );

        let router = Router::with_path("/pets/{id}").get(get_pet_by_id);
        let doc = doc.merge_router(&router);

        assert_eq!(
            Value::from_str(
                r#"{
                    "openapi": "3.1.0",
                    "info": {
                       "title": "my application",
                       "version": "0.1.0"
                    },
                    "servers": [
                       {
                          "url": "/api/bar/",
                          "description": "this is description of the server",
                          "variables": {
                             "username": {
                                "default": "the_user",
                                "description": "this is user"
                             }
                          }
                       }
                    ],
                    "paths": {
                       "/pets/{id}": {
                          "get": {
                             "summary": "Get pet by id",
                             "description": "Get pet from database by pet database id",
                             "operationId": "salvo_oapi.openapi.tests.test_simple_document_with_security.get_pet_by_id",
                             "parameters": [
                                {
                                   "name": "pet_id",
                                   "in": "path",
                                   "description": "Get parameter `pet_id` from request url path.",
                                   "required": true,
                                   "schema": {
                                      "type": "integer",
                                      "format": "uint64",
                                      "minimum": 0
                                   }
                                },
                                {
                                   "name": "id",
                                   "in": "path",
                                   "description": "Pet database id to get Pet for",
                                   "required": true
                                }
                             ],
                             "responses": {
                                "200": {
                                   "description": "Pet found successfully"
                                },
                                "404": {
                                   "description": "Pet was not found"
                                }
                             },
                             "security": [
                                {},
                                {
                                   "my_auth": [
                                      "read:items",
                                      "edit:items"
                                   ]
                                },
                                {
                                   "token_jwt": []
                                },
                                {
                                    "api_key1": [],
                                    "api_key2": []
                                }
                             ]
                          }
                       }
                    },
                    "components": {
                       "schemas": {
                          "salvo_oapi.openapi.tests.test_simple_document_with_security.Pet": {
                             "type": "object",
                             "required": [
                                "id",
                                "name"
                             ],
                             "properties": {
                                "age": {
                                   "type": ["integer", "null"],
                                   "format": "int32"
                                },
                                "id": {
                                   "type": "integer",
                                   "format": "uint64",
                                   "minimum": 0
                                },
                                "name": {
                                   "type": "string"
                                }
                             },
                             "examples": [{
                                "id": 1,
                                "name": "bob the cat"
                             }]
                          }
                       },
                       "securitySchemes": {
                          "token_jwt": {
                             "type": "http",
                             "scheme": "bearer",
                             "bearerFormat": "JWT"
                          }
                       }
                    }
                 }"#
            )
            .unwrap(),
            Value::from_str(&doc.to_json().unwrap()).unwrap()
        );
    }

    #[test]
    fn merge_router_normalizes_constrained_path_params() {
        #[salvo_oapi::endpoint]
        async fn get_post(id: PathParam<i32>) -> &'static str {
            let _ = id;
            "ok"
        }

        let router = Router::with_path("/posts/{id:num}").get(get_post);
        let doc = OpenApi::new("test api", "0.0.1").merge_router(&router);

        assert!(doc.paths.contains_key("/posts/{id}"));
        assert!(!doc.paths.contains_key("/posts/{id:num}"));
    }

    #[test]
    fn to_parameters_struct_defaults_to_query_with_required() {
        // Regression test for https://github.com/salvo-rs/salvo/issues/1609
        // A struct used directly as a handler argument extracts from the query string by
        // default, so its parameters must be reported with `in: query`. Non-`Option` fields
        // must be `required: true`, and `Option` fields `required: false`. Previously the
        // parameter location fell back to `ParameterIn::Path`, which mislabeled the location
        // and forced every field to `required: true`.
        #[derive(Deserialize, crate::ToParameters)]
        #[allow(dead_code)]
        struct ListQuery {
            page: i32,
            #[serde(rename = "pageSize")]
            page_size: i32,
            name: String,
            keyword: Option<String>,
        }

        #[salvo_oapi::endpoint]
        async fn list(query: ListQuery) -> &'static str {
            let _ = query;
            "ok"
        }

        let router = Router::with_path("/list").get(list);
        let doc = OpenApi::new("test api", "0.0.1").merge_router(&router);

        let path_item = doc.paths.get("/list").expect("/list entry should exist");
        let operation = path_item
            .operations
            .get(&PathItemType::Get)
            .expect("get operation should exist");

        let by_name = |name: &str| {
            operation
                .parameters
                .0
                .iter()
                .find(|p| p.name == name)
                .unwrap_or_else(|| panic!("parameter `{name}` should exist"))
        };

        for name in ["page", "pageSize", "name", "keyword"] {
            assert_eq!(
                by_name(name).parameter_in,
                ParameterIn::Query,
                "parameter `{name}` should be located in query"
            );
        }
        assert_eq!(by_name("page").required, Required::True);
        assert_eq!(by_name("pageSize").required, Required::True);
        assert_eq!(by_name("name").required, Required::True);
        assert_eq!(by_name("keyword").required, Required::False);
    }

    #[test]
    fn to_parameters_accepts_singular_and_plural_keys() {
        // The container key was `parameters(...)` and the field key `parameter(...)`;
        // the opposite spelling used to be a hard error / silently ignored. Both
        // spellings are now accepted at both levels, so the drift is invisible to
        // users. This test drives each level with its *alias* spelling.
        #[derive(Deserialize, crate::ToParameters)]
        // singular `parameter(...)` on the container (previously an error):
        #[salvo(parameter(default_parameter_in = Header))]
        #[allow(dead_code)]
        struct AliasQuery {
            page: i32,
            // plural `parameters(...)` on a field (previously ignored):
            #[salvo(parameters(rename = "renamed"))]
            raw: String,
        }

        #[salvo_oapi::endpoint]
        async fn list(query: AliasQuery) -> &'static str {
            let _ = query;
            "ok"
        }

        let router = Router::with_path("/alias").get(list);
        let doc = OpenApi::new("test api", "0.0.1").merge_router(&router);
        let operation = doc
            .paths
            .get("/alias")
            .and_then(|item| item.operations.get(&PathItemType::Get))
            .expect("get operation should exist");
        let names: Vec<&str> = operation
            .parameters
            .0
            .iter()
            .map(|p| p.name.as_str())
            .collect();

        // container singular alias honored: every parameter is in `header`.
        for param in &operation.parameters.0 {
            assert_eq!(
                param.parameter_in,
                ParameterIn::Header,
                "parameter `{}` should inherit the container `default_parameter_in`",
                param.name
            );
        }
        // field plural alias honored: `raw` was renamed to `renamed`.
        assert!(
            names.contains(&"renamed"),
            "field rename alias not applied: {names:?}"
        );
        assert!(!names.contains(&"raw"));
    }

    #[test]
    fn merge_router_skips_route_without_method_filter() {
        #[salvo_oapi::endpoint]
        async fn any_handler() -> &'static str {
            "ok"
        }

        // `goal()` does not attach a method filter; the route matches every HTTP method.
        // OpenAPI 3.1 has no equivalent "any" operation, so the route should be skipped
        // rather than fabricating four operations under it.
        let router = Router::with_path("/no-method").goal(any_handler);
        let doc = OpenApi::new("test api", "0.0.1").merge_router(&router);

        assert!(
            !doc.paths.contains_key("/no-method"),
            "expected no path entry when the route lacks a method filter; \
             got: {:?}",
            doc.paths.keys().collect::<Vec<_>>()
        );
    }

    #[test]
    fn merge_router_emits_query_operation_only_for_3_2() {
        #[salvo_oapi::endpoint]
        async fn search() -> &'static str {
            "ok"
        }

        let router = Router::with_path("/search").query(search);

        // `query` is an OpenAPI 3.2 Path Item field, so a 3.1 document must not carry it.
        let doc_3_1 = OpenApi::new("test api", "0.0.1").merge_router(&router);
        assert!(
            !doc_3_1.paths.contains_key("/search"),
            "QUERY must not be emitted into a 3.1 document"
        );

        let doc_3_2 = OpenApi::new("test api", "0.0.1")
            .openapi_version(OpenApiVersion::Version3_2)
            .merge_router(&router);
        let path_item = doc_3_2
            .paths
            .get("/search")
            .expect("/search entry should exist");
        assert!(path_item.operations.contains_key(&PathItemType::Query));
    }

    #[test]
    fn merge_router_emits_custom_method_as_additional_operation() {
        use salvo_core::http::Method;

        #[salvo_oapi::endpoint]
        async fn purge() -> &'static str {
            "ok"
        }

        let router = Router::with_path("/cache")
            .filter(salvo_core::routing::filters::MethodFilter(
                Method::from_bytes(b"PURGE").expect("valid method"),
            ))
            .goal(purge);

        let doc_3_1 = OpenApi::new("test api", "0.0.1").merge_router(&router);
        assert!(
            !doc_3_1.paths.contains_key("/cache"),
            "custom methods must not be emitted into a 3.1 document"
        );

        let doc_3_2 = OpenApi::new("test api", "0.0.1")
            .openapi_version(OpenApiVersion::Version3_2)
            .merge_router(&router);
        let path_item = doc_3_2
            .paths
            .get("/cache")
            .expect("/cache entry should exist");
        assert!(path_item.operations.is_empty());
        assert!(path_item.additional_operations.contains_key("PURGE"));
    }

    #[test]
    fn merge_router_attaches_only_to_explicit_method() {
        #[salvo_oapi::endpoint]
        async fn delete_thing() -> &'static str {
            "ok"
        }

        // Sanity check that explicit method filters still work and do not pull in
        // sibling methods (a regression guard against the prior 4-method fan-out).
        let router = Router::with_path("/thing").delete(delete_thing);
        let doc = OpenApi::new("test api", "0.0.1").merge_router(&router);

        let path_item = doc.paths.get("/thing").expect("/thing entry should exist");
        assert!(path_item.operations.contains_key(&PathItemType::Delete));
        assert!(!path_item.operations.contains_key(&PathItemType::Get));
        assert!(!path_item.operations.contains_key(&PathItemType::Post));
        assert!(!path_item.operations.contains_key(&PathItemType::Put));
        assert!(!path_item.operations.contains_key(&PathItemType::Patch));
    }

    #[test]
    fn test_build_openapi() {
        let _doc = OpenApi::new("pet api", "0.1.0")
            .info(Info::new("my pet api", "0.2.0"))
            .servers(Servers::new())
            .add_path(
                "/api/v1",
                PathItem::new(PathItemType::Get, Operation::new()),
            )
            .security([SecurityRequirement::default()])
            .add_security_scheme(
                "api_key",
                SecurityScheme::ApiKey(ApiKey::Header(ApiKeyValue::new("todo_apikey"))),
            )
            .extend_security_schemes([(
                "TLS",
                SecurityScheme::MutualTls {
                    description: None,
                    deprecated: None,
                },
            )])
            .add_schema("example", Schema::object(Object::new()))
            .extend_schemas([("", Schema::from(Object::new()))])
            .response("200", Response::new("OK"))
            .extend_responses([("404", Response::new("Not Found"))])
            .tags(["tag1", "tag2"])
            .external_docs(ExternalDocs::default())
            .into_router("/openapi/doc");
    }

    #[test]
    fn json_schema_dialect_serializes_under_spec_field_name() -> Result<(), serde_json::Error> {
        let doc = OpenApi::new("api", "0.1.0")
            .json_schema_dialect("https://json-schema.org/draft/2020-12/schema");
        let value: Value = serde_json::from_str(&doc.to_json()?)?;

        assert_eq!(
            value["jsonSchemaDialect"],
            Value::String("https://json-schema.org/draft/2020-12/schema".to_owned()),
            "expected top-level `jsonSchemaDialect` field per OpenAPI 3.1.0"
        );
        assert!(
            value.get("$schema").is_none(),
            "`$schema` is the JSON Schema keyword inside Schema Objects, not the OpenAPI \
             document-level field"
        );
        Ok(())
    }

    #[test]
    fn json_schema_dialect_omits_field_when_empty() -> Result<(), serde_json::Error> {
        let doc = OpenApi::new("api", "0.1.0");
        let value: Value = serde_json::from_str(&doc.to_json()?)?;

        assert!(value.get("jsonSchemaDialect").is_none());
        assert!(value.get("$schema").is_none());
        Ok(())
    }

    #[test]
    fn webhooks_omits_field_when_empty() -> Result<(), serde_json::Error> {
        let doc = OpenApi::new("api", "0.1.0");
        let value: Value = serde_json::from_str(&doc.to_json()?)?;

        assert!(value.get("webhooks").is_none());
        Ok(())
    }

    #[test]
    fn webhooks_serializes_inline_path_item() -> Result<(), serde_json::Error> {
        let doc = OpenApi::new("api", "0.1.0").add_webhook(
            "newPet",
            PathItem::new(
                PathItemType::Post,
                Operation::new().add_response("200", Response::new("acknowledged")),
            ),
        );
        let value: Value = serde_json::from_str(&doc.to_json()?)?;

        assert_eq!(
            value["webhooks"],
            json!({
                "newPet": {
                    "post": {
                        "responses": {
                            "200": { "description": "acknowledged" }
                        }
                    }
                }
            })
        );
        Ok(())
    }

    #[test]
    fn webhooks_serializes_reference_object() -> Result<(), serde_json::Error> {
        let doc = OpenApi::new("api", "0.1.0").add_webhook(
            "newPet",
            RefOr::Ref(Ref::new("#/components/pathItems/NewPetWebhook")),
        );
        let value: Value = serde_json::from_str(&doc.to_json()?)?;

        assert_eq!(
            value["webhooks"]["newPet"],
            json!({ "$ref": "#/components/pathItems/NewPetWebhook" })
        );
        Ok(())
    }

    #[test]
    fn webhooks_merge_combines_entries() {
        let api_a = OpenApi::new("a", "1.0").add_webhook(
            "newPet",
            PathItem::new(PathItemType::Post, Operation::new()),
        );
        let api_b = OpenApi::new("b", "1.0").add_webhook(
            "deletedPet",
            PathItem::new(PathItemType::Post, Operation::new()),
        );

        let merged = api_a.merge(api_b);

        assert!(merged.webhooks.contains_key("newPet"));
        assert!(merged.webhooks.contains_key("deletedPet"));
    }

    #[test]
    fn test_openapi_to_pretty_json() -> Result<(), serde_json::Error> {
        let raw_json = r#"{
            "openapi": "3.1.0",
            "info": {
                "title": "My api",
                "description": "My api description",
                "license": {
                "name": "MIT",
                "url": "http://mit.licence"
                },
                "version": "1.0.0",
                "contact": {},
                "termsOfService": "terms of service"
            },
            "paths": {}
        }"#;
        let doc: OpenApi = OpenApi::with_info(
            Info::default()
                .description("My api description")
                .license(License::new("MIT").url("http://mit.licence"))
                .title("My api")
                .version("1.0.0")
                .terms_of_service("terms of service")
                .contact(Contact::default()),
        );
        let serialized = doc.to_pretty_json()?;

        assert_eq!(
            Value::from_str(&serialized)?,
            Value::from_str(raw_json)?,
            "expected serialized json to match raw: \nserialized: \n{serialized} \nraw: \n{raw_json}"
        );
        Ok(())
    }

    #[test]
    fn test_deprecated_from_bool() {
        assert_eq!(Deprecated::True, Deprecated::from(true));
        assert_eq!(Deprecated::False, Deprecated::from(false));
    }

    #[test]
    fn test_deprecated_deserialize() {
        let deserialize_result = serde_json::from_str::<Deprecated>("true");
        assert_eq!(deserialize_result.unwrap(), Deprecated::True);
        let deserialize_result = serde_json::from_str::<Deprecated>("false");
        assert_eq!(deserialize_result.unwrap(), Deprecated::False);
    }

    #[test]
    fn test_required_from_bool() {
        assert_eq!(Required::True, Required::from(true));
        assert_eq!(Required::False, Required::from(false));
    }

    #[test]
    fn test_required_deserialize() {
        let deserialize_result = serde_json::from_str::<Required>("true");
        assert_eq!(deserialize_result.unwrap(), Required::True);
        let deserialize_result = serde_json::from_str::<Required>("false");
        assert_eq!(deserialize_result.unwrap(), Required::False);
    }

    #[tokio::test]
    async fn test_openapi_handle() {
        let doc = OpenApi::new("pet api", "0.1.0");
        let mut req = Request::new();
        let mut depot = Depot::new();
        let mut res = salvo_core::Response::new();
        let mut ctrl = FlowCtrl::default();
        doc.handle(&mut req, &mut depot, &mut res, &mut ctrl).await;

        let bytes = match res.body.take() {
            ResBody::Once(bytes) => bytes,
            _ => Bytes::new(),
        };

        assert_eq!(
            res.content_type()
                .expect("content type should exist")
                .to_string(),
            "application/json; charset=utf-8".to_owned()
        );
        assert_eq!(
            bytes,
            Bytes::from_static(
                b"{\"openapi\":\"3.1.0\",\"info\":{\"title\":\"pet api\",\"version\":\"0.1.0\"},\"paths\":{}}"
            )
        );
    }

    #[tokio::test]
    async fn test_openapi_handle_pretty() {
        let doc = OpenApi::new("pet api", "0.1.0");

        let mut req = Request::new();
        req.queries_mut()
            .insert("pretty".to_owned(), "true".to_owned());

        let mut depot = Depot::new();
        let mut res = salvo_core::Response::new();
        let mut ctrl = FlowCtrl::default();
        doc.handle(&mut req, &mut depot, &mut res, &mut ctrl).await;

        let bytes = match res.body.take() {
            ResBody::Once(bytes) => bytes,
            _ => Bytes::new(),
        };

        assert_eq!(
            res.content_type()
                .expect("content type should exist")
                .to_string(),
            "application/json; charset=utf-8".to_owned()
        );
        assert_eq!(
            bytes,
            Bytes::from_static(b"{\n  \"openapi\": \"3.1.0\",\n  \"info\": {\n    \"title\": \"pet api\",\n    \"version\": \"0.1.0\"\n  },\n  \"paths\": {}\n}")
        );
    }

    #[test]
    fn test_openapi_schema_work_with_generics() {
        // Reset global namer state to ensure deterministic test results
        crate::naming::set_namer(crate::naming::FlexNamer::new());

        #[derive(Serialize, Deserialize, Clone, Debug, ToSchema)]
        #[salvo(schema(name = City))]
        pub(crate) struct CityDTO {
            #[salvo(schema(rename = "id"))]
            pub(crate) id: String,
            #[salvo(schema(rename = "name"))]
            pub(crate) name: String,
        }

        #[derive(Serialize, Deserialize, Debug, ToSchema)]
        #[salvo(schema(name = Response))]
        pub(crate) struct ApiResponse<T: Serialize + ToSchema + Send + Debug + 'static> {
            #[salvo(schema(rename = "status"))]
            /// status code
            pub(crate) status: String,
            #[salvo(schema(rename = "msg"))]
            /// Status msg
            pub(crate) message: String,
            #[salvo(schema(rename = "data"))]
            /// The data returned
            pub(crate) data: T,
        }

        #[salvo_oapi::endpoint(
            operation_id = "get_all_cities",
            tags("city"),
            status_codes(200, 400, 401, 403, 500)
        )]
        pub async fn get_all_cities() -> Result<Json<ApiResponse<Vec<CityDTO>>>, StatusError> {
            Ok(Json(ApiResponse {
                status: "200".to_owned(),
                message: "OK".to_owned(),
                data: vec![CityDTO {
                    id: "1".to_owned(),
                    name: "Beijing".to_owned(),
                }],
            }))
        }

        let doc = salvo_oapi::OpenApi::new("my application", "0.1.0")
            .add_server(Server::new("/api/bar/").description("this is description of the server"));

        let router = Router::with_path("/cities").get(get_all_cities);
        let doc = doc.merge_router(&router);

        assert_eq!(
            json! {{
                "openapi": "3.1.0",
                "info": {
                    "title": "my application",
                    "version": "0.1.0"
                },
                "servers": [
                    {
                        "url": "/api/bar/",
                        "description": "this is description of the server"
                    }
                ],
                "paths": {
                    "/cities": {
                        "get": {
                            "tags": [
                                "city"
                            ],
                            "operationId": "get_all_cities",
                            "responses": {
                                "200": {
                                    "description": "Response with json format data",
                                    "content": {
                                        "application/json": {
                                            "schema": {
                                                "$ref": "#/components/schemas/Response<alloc.vec.Vec<City>>"
                                            }
                                        }
                                    }
                                },
                                "400": {
                                    "description": "The request could not be understood by the server due to malformed syntax.",
                                    "content": {
                                        "application/json": {
                                            "schema": {
                                                "$ref": "#/components/schemas/salvo_core.http.errors.status_error.StatusError"
                                            }
                                        }
                                    }
                                },
                                "401": {
                                    "description": "The request requires user authentication.",
                                    "content": {
                                        "application/json": {
                                            "schema": {
                                                "$ref": "#/components/schemas/salvo_core.http.errors.status_error.StatusError"
                                            }
                                        }
                                    }
                                },
                                "403": {
                                    "description": "The server refused to authorize the request.",
                                    "content": {
                                        "application/json": {
                                            "schema": {
                                                "$ref": "#/components/schemas/salvo_core.http.errors.status_error.StatusError"
                                            }
                                        }
                                    }
                                },
                                "500": {
                                    "description": "The server encountered an internal error while processing this request.",
                                    "content": {
                                        "application/json": {
                                            "schema": {
                                                "$ref": "#/components/schemas/salvo_core.http.errors.status_error.StatusError"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "components": {
                    "schemas": {
                        "City": {
                            "type": "object",
                            "required": [
                                "id",
                                "name"
                            ],
                            "properties": {
                                "id": {
                                    "type": "string"
                                },
                                "name": {
                                    "type": "string"
                                }
                            }
                        },
                        "Response<alloc.vec.Vec<City>>": {
                            "type": "object",
                            "required": [
                                "status",
                                "msg",
                                "data"
                            ],
                            "properties": {
                                "data": {
                                    "allOf": [
                                        {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/City"
                                            }
                                        },
                                        {
                                            "description": "The data returned"
                                        }
                                    ]
                                },
                                "msg": {
                                    "type": "string",
                                    "description": "Status msg"
                                },
                                "status": {
                                    "type": "string",
                                    "description": "status code"
                                }
                            }
                        },
                        "salvo_core.http.errors.status_error.StatusError": {
                            "type": "object",
                            "required": [
                                "code",
                                "name",
                                "brief",
                                "detail"
                            ],
                            "properties": {
                                "brief": {
                                    "type": "string"
                                },
                                "cause": {
                                    "type": "string"
                                },
                                "code": {
                                    "type": "integer",
                                    "format": "uint16",
                                    "minimum": 0
                                },
                                "detail": {
                                    "type": "string"
                                },
                                "name": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            }},
            Value::from_str(&doc.to_json().unwrap()).unwrap()
        );
    }
}