rapina 0.13.0

//! OpenAPI 3.0 specification structures

use serde::Serialize;
use std::collections::BTreeMap;

#[derive(Debug, Clone, Serialize)]
pub struct OpenApiSpec {
    pub openapi: String,
    pub info: Info,
    pub paths: BTreeMap<String, PathItem>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub components: Option<Components>,
}

impl OpenApiSpec {
    pub fn new(title: impl Into<String>, version: impl Into<String>) -> Self {
        Self {
            openapi: "3.0.3".to_string(),
            info: Info {
                title: title.into(),
                version: version.into(),
                description: None,
            },
            paths: BTreeMap::new(),
            components: None,
        }
    }
}

/// API metadata
#[derive(Debug, Clone, Serialize)]
pub struct Info {
    pub title: String,
    pub version: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
}

/// Operations available on a single path
#[derive(Debug, Clone, Serialize, Default)]
pub struct PathItem {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub get: Option<Operation>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub post: Option<Operation>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub put: Option<Operation>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub delete: Option<Operation>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub patch: Option<Operation>,
}

/// A single API operation (endpoint)
#[derive(Debug, Clone, Serialize)]
pub struct Operation {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub summary: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    #[serde(rename = "operationId", skip_serializing_if = "Option::is_none")]
    pub operation_id: Option<String>,
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub parameters: Vec<Parameter>,
    #[serde(rename = "requestBody", skip_serializing_if = "Option::is_none")]
    pub request_body: Option<RequestBody>,
    pub responses: BTreeMap<String, Response>,
}

impl Default for Operation {
    fn default() -> Self {
        let mut responses = BTreeMap::new();
        responses.insert(
            "200".to_string(),
            Response {
                description: "Success".to_string(),
                content: None,
            },
        );
        Self {
            summary: None,
            description: None,
            operation_id: None,
            parameters: Vec::new(),
            request_body: None,
            responses,
        }
    }
}

/// Path, Query, or header parameter
#[derive(Debug, Clone, Serialize)]
pub struct Parameter {
    pub name: String,
    #[serde(rename = "in")]
    pub location: ParameterLocation,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    pub required: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub schema: Option<Schema>,
}

#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum ParameterLocation {
    Path,
    Query,
    Header,
}

/// Request body definition
#[derive(Debug, Clone, Serialize)]
pub struct RequestBody {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    pub required: bool,
    pub content: BTreeMap<String, MediaType>,
}

/// Response definition
#[derive(Debug, Clone, Serialize)]
pub struct Response {
    pub description: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub content: Option<BTreeMap<String, MediaType>>,
}

/// MediaType with schema
#[derive(Debug, Clone, Serialize)]
pub struct MediaType {
    pub schema: Schema,
}

/// JSON Schema (simplified)
#[derive(Debug, Clone, Serialize)]
#[serde(untagged)]
pub enum Schema {
    Ref {
        #[serde(rename = "$ref")]
        reference: String,
    },
    Inline(serde_json::Value),
}

/// Reusable components
#[derive(Debug, Clone, Serialize, Default)]
pub struct Components {
    #[serde(skip_serializing_if = "BTreeMap::is_empty")]
    pub schemas: BTreeMap<String, serde_json::Value>,
}

/// Generate a JSON Schema for type `T` using OpenAPI 3.0-compatible settings.
///
/// This uses `SchemaSettings::openapi3()` which replaces boolean schemas
/// (`true`/`false`) with object equivalents (`{}`/`{"not": {}}`) that are
/// valid in OpenAPI 3.0.x.
pub fn openapi_schema_for<T: schemars::JsonSchema>() -> serde_json::Value {
    let schema = schemars::generate::SchemaSettings::openapi3()
        .into_generator()
        .into_root_schema_for::<T>();
    serde_json::to_value(schema).unwrap()
}

/// Create the standard Rapina error response schema
fn error_response_schema() -> serde_json::Value {
    serde_json::json!({
        "type": "object",
        "required": ["error", "trace_id"],
        "properties": {
        "error": {
                "type": "object",
                "required": ["code", "message"],
                "properties": {
                    "code": {"type": "string", "description": "Machine-readable error code"},
                    "message": {"type": "string", "description": "Human-readable error message"},
                    "details": {"type": "object", "description": "Optional additional details", "additionalProperties": true}
                }
            }
    }
    })
}

fn error_response_ref() -> Response {
    let mut content = BTreeMap::new();
    content.insert(
        "application/json".to_string(),
        MediaType {
            schema: Schema::Ref {
                reference: "#/components/schemas/ErrorResponse".to_string(),
            },
        },
    );
    Response {
        description: "Error response".to_string(),
        content: Some(content),
    }
}

/// Convert a snake_case handler name to a human-readable summary.
/// e.g., "list_todos" -> "List todos", "get_todo" -> "Get todo"
fn humanize_handler_name(name: &str) -> String {
    let words: Vec<&str> = name.split('_').collect();
    let mut result = String::new();
    for (i, word) in words.iter().enumerate() {
        if i > 0 {
            result.push(' ');
        }
        if i == 0 {
            let mut chars = word.chars();
            if let Some(c) = chars.next() {
                result.extend(c.to_uppercase());
                result.push_str(chars.as_str());
            }
        } else {
            result.push_str(word);
        }
    }
    result
}

pub fn build_openapi_spec(
    title: &str,
    version: &str,
    routes: &[crate::introspection::RouteInfo],
) -> OpenApiSpec {
    let mut spec = OpenApiSpec::new(title, version);

    let mut schemas = BTreeMap::new();
    schemas.insert("ErrorResponse".to_string(), error_response_schema());

    spec.components = Some(Components { schemas });

    let mut seen_operation_ids: std::collections::HashSet<&str> = std::collections::HashSet::new();

    for route in routes {
        if route.is_internal() {
            continue;
        }

        if !seen_operation_ids.insert(&route.handler_name) {
            panic!(
                "Duplicate operationId '{}' in OpenAPI spec. Each handler must have a unique name. \
                 Found duplicate on {} {}.",
                route.handler_name, route.method, route.path
            );
        }
        // Extract path parameters (e.g., :id -> id)
        let mut params: Vec<Parameter> = route
            .path
            .split('/')
            .filter(|s| s.starts_with(':'))
            .map(|s| Parameter {
                name: s.trim_start_matches(':').to_string(),
                location: ParameterLocation::Path,
                description: None,
                required: true,
                schema: None,
            })
            .collect();

        // Append typed header parameters
        for h in &route.header_parameters {
            params.push(Parameter {
                name: h.name.clone(),
                location: ParameterLocation::Header,
                description: None,
                required: h.required,
                schema: Some(Schema::Inline(serde_json::json!({"type": "string"}))),
            });
        }

        // Convert :param to {param} for OpenAPI format
        let openapi_path = route
            .path
            .split('/')
            .map(|s| {
                if s.starts_with(':') {
                    format!("{{{}}}", s.trim_start_matches(':'))
                } else {
                    s.to_string()
                }
            })
            .collect::<Vec<_>>()
            .join("/");

        let success_response = if let Some(schema) = &route.response_schema {
            let mut content = BTreeMap::new();
            content.insert(
                "application/json".to_string(),
                MediaType {
                    schema: Schema::Inline(schema.clone()),
                },
            );
            Response {
                description: "Success".to_string(),
                content: Some(content),
            }
        } else {
            Response {
                description: "Success".to_string(),
                content: None,
            }
        };

        let summary = humanize_handler_name(&route.handler_name);

        let mut operation = Operation {
            summary: Some(summary),
            operation_id: Some(route.handler_name.clone()),
            parameters: params,
            ..Default::default()
        };

        // Add request body schema if present
        if let Some(schema) = &route.request_schema {
            let content_type = route
                .request_content_type
                .as_deref()
                .unwrap_or("application/json");
            let mut content = BTreeMap::new();
            content.insert(
                content_type.to_string(),
                MediaType {
                    schema: Schema::Inline(schema.clone()),
                },
            );
            operation.request_body = Some(RequestBody {
                description: None,
                required: route.request_body_required.unwrap_or(true),
                content,
            });
        }

        operation
            .responses
            .insert("200".to_string(), success_response);

        // Add documented error responses
        for error in &route.error_responses {
            let status_key = error.status.to_string();
            let error_desc = error.description.to_string();
            operation.responses.entry(status_key).or_insert_with(|| {
                let mut content = BTreeMap::new();
                content.insert(
                    "application/json".to_string(),
                    MediaType {
                        schema: Schema::Ref {
                            reference: "#/components/schemas/ErrorResponse".to_string(),
                        },
                    },
                );
                Response {
                    description: error_desc,
                    content: Some(content),
                }
            });
        }

        // Add default error response for undocumented errors
        operation
            .responses
            .insert("default".to_string(), error_response_ref());

        let path_item = spec.paths.entry(openapi_path).or_default();

        match route.method.to_uppercase().as_str() {
            "GET" => path_item.get = Some(operation),
            "POST" => path_item.post = Some(operation),
            "PUT" => path_item.put = Some(operation),
            "DELETE" => path_item.delete = Some(operation),
            "PATCH" => path_item.patch = Some(operation),
            _ => {}
        }
    }

    spec
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::error::ErrorVariant;
    use crate::introspection::RouteInfo;

    #[test]
    fn test_build_openapi_spec_basic() {
        let routes = vec![RouteInfo::new(
            "GET",
            "/users",
            "list_users",
            None,
            None,
            None::<String>,
            None,
            Vec::new(),
            Vec::new(),
            None::<String>,
        )];
        let spec = build_openapi_spec("Test API", "1.0.0", &routes);

        assert_eq!(spec.info.title, "Test API");
        assert_eq!(spec.info.version, "1.0.0");
        assert!(spec.paths.contains_key("/users"));
    }

    #[test]
    fn test_build_openapi_spec_with_error_responses() {
        let errors = vec![
            ErrorVariant {
                status: 404,
                code: "NOT_FOUND",
                description: "User not found",
            },
            ErrorVariant {
                status: 409,
                code: "CONFLICT",
                description: "Email already taken",
            },
        ];
        let routes = vec![RouteInfo::new(
            "GET",
            "/users/:id",
            "get_user",
            None,
            None,
            None::<String>,
            None,
            errors,
            Vec::new(),
            None::<String>,
        )];
        let spec = build_openapi_spec("Test API", "1.0.0", &routes);

        let path = spec.paths.get("/users/{id}").unwrap();
        let get_op = path.get.as_ref().unwrap();

        // Should have 200, 404, 409, and default responses
        assert!(get_op.responses.contains_key("200"));
        assert!(get_op.responses.contains_key("404"));
        assert!(get_op.responses.contains_key("409"));
        assert!(get_op.responses.contains_key("default"));

        // Check descriptions
        assert_eq!(
            get_op.responses.get("404").unwrap().description,
            "User not found"
        );
        assert_eq!(
            get_op.responses.get("409").unwrap().description,
            "Email already taken"
        );
    }

    #[test]
    fn test_openapi_schema_for_serde_json_value() {
        let schema = openapi_schema_for::<serde_json::Value>();
        // Must be an object schema, not boolean true
        assert!(
            schema.is_object(),
            "serde_json::Value schema should be an object, got: {schema}"
        );
        assert!(
            !schema.is_boolean(),
            "serde_json::Value schema should not be boolean"
        );
    }

    #[test]
    fn test_openapi_schema_for_option_serde_json_value() {
        let schema = openapi_schema_for::<Option<serde_json::Value>>();
        assert!(schema.is_object());
    }

    #[test]
    fn test_openapi_schema_for_struct_with_value_field() {
        #[derive(schemars::JsonSchema)]
        struct TestDto {
            #[allow(dead_code)]
            opts: Option<serde_json::Value>,
        }
        let schema = openapi_schema_for::<TestDto>();
        let properties = schema.get("properties").unwrap();
        let opts = properties.get("opts").unwrap();
        assert!(
            opts.is_object(),
            "opts field schema should be an object, got: {opts}"
        );
    }

    #[test]
    fn test_build_openapi_spec_with_value_response_schema() {
        #[derive(schemars::JsonSchema)]
        struct DtoWithValue {
            #[allow(dead_code)]
            data: String,
            #[allow(dead_code)]
            opts: Option<serde_json::Value>,
        }
        let schema = openapi_schema_for::<DtoWithValue>();
        let routes = vec![RouteInfo::new(
            "POST",
            "/items",
            "create_item",
            Some(schema),
            None,
            None::<String>,
            None,
            Vec::new(),
            Vec::new(),
            None::<String>,
        )];
        let spec = build_openapi_spec("Test API", "1.0.0", &routes);

        let json = serde_json::to_value(&spec).unwrap();
        let opts_schema = &json["paths"]["/items"]["post"]["responses"]["200"]["content"]["application/json"]
            ["schema"]["properties"]["opts"];

        assert!(
            !opts_schema.is_boolean(),
            "opts should not be a boolean schema, got: {opts_schema}"
        );
        assert!(
            opts_schema.is_object(),
            "opts should be an object schema, got: {opts_schema}"
        );
    }

    #[test]
    fn test_build_openapi_spec_skips_internal_routes() {
        let routes = vec![
            RouteInfo::new(
                "GET",
                "/__rapina/routes",
                "internal",
                None,
                None,
                None::<String>,
                None,
                Vec::new(),
                Vec::new(),
                None::<String>,
            ),
            RouteInfo::new(
                "GET",
                "/users",
                "list_users",
                None,
                None,
                None::<String>,
                None,
                Vec::new(),
                Vec::new(),
                None::<String>,
            ),
        ];
        let spec = build_openapi_spec("Test API", "1.0.0", &routes);

        assert!(!spec.paths.contains_key("/__rapina/routes"));
        assert!(spec.paths.contains_key("/users"));
    }

    #[test]
    fn test_build_openapi_spec_with_request_body() {
        #[derive(schemars::JsonSchema)]
        struct CreateUserRequest {
            #[allow(dead_code)]
            name: String,
            #[allow(dead_code)]
            email: String,
        }
        let request_schema = openapi_schema_for::<CreateUserRequest>();
        let routes = vec![RouteInfo::new(
            "POST",
            "/users",
            "create_user",
            None,
            Some(request_schema),
            Some("application/json"),
            Some(true),
            Vec::new(),
            Vec::new(),
            None::<String>,
        )];
        let spec = build_openapi_spec("Test API", "1.0.0", &routes);

        let path = spec.paths.get("/users").unwrap();
        let post_op = path.post.as_ref().unwrap();

        // Should have requestBody
        assert!(post_op.request_body.is_some());
        let request_body = post_op.request_body.as_ref().unwrap();
        assert!(request_body.required);
        assert!(request_body.content.contains_key("application/json"));
    }

    #[test]
    fn test_build_openapi_spec_with_form_request_body() {
        #[derive(schemars::JsonSchema)]
        struct LoginForm {
            #[allow(dead_code)]
            username: String,
            #[allow(dead_code)]
            password: String,
        }
        let request_schema = openapi_schema_for::<LoginForm>();
        let routes = vec![RouteInfo::new(
            "POST",
            "/login",
            "login",
            None,
            Some(request_schema),
            Some("application/x-www-form-urlencoded"),
            Some(true),
            Vec::new(),
            Vec::new(),
            None::<String>,
        )];
        let spec = build_openapi_spec("Test API", "1.0.0", &routes);

        let path = spec.paths.get("/login").unwrap();
        let post_op = path.post.as_ref().unwrap();

        // Should have requestBody with form content type
        assert!(post_op.request_body.is_some());
        let request_body = post_op.request_body.as_ref().unwrap();
        assert!(request_body.required);
        assert!(
            request_body
                .content
                .contains_key("application/x-www-form-urlencoded")
        );
        assert!(!request_body.content.contains_key("application/json"));
    }

    #[test]
    fn test_build_openapi_spec_with_optional_request_body() {
        #[derive(schemars::JsonSchema)]
        struct UpdateUserRequest {
            #[allow(dead_code)]
            name: Option<String>,
        }
        let request_schema = openapi_schema_for::<UpdateUserRequest>();
        let routes = vec![RouteInfo::new(
            "PATCH",
            "/users/:id",
            "update_user",
            None,
            Some(request_schema),
            Some("application/json"),
            Some(false), // optional request body
            Vec::new(),
            Vec::new(),
            None::<String>,
        )];
        let spec = build_openapi_spec("Test API", "1.0.0", &routes);

        let path = spec.paths.get("/users/{id}").unwrap();
        let patch_op = path.patch.as_ref().unwrap();

        // Should have requestBody with required: false
        assert!(patch_op.request_body.is_some());
        let request_body = patch_op.request_body.as_ref().unwrap();
        assert!(!request_body.required);
        assert!(request_body.content.contains_key("application/json"));
    }

    #[test]
    fn test_unique_operation_ids_pass() {
        let routes = vec![
            RouteInfo::new(
                "GET",
                "/users",
                "list_users",
                None,
                None,
                None::<String>,
                None,
                Vec::new(),
                Vec::new(),
                None::<String>,
            ),
            RouteInfo::new(
                "POST",
                "/users",
                "create_user",
                None,
                None,
                None::<String>,
                None,
                Vec::new(),
                Vec::new(),
                None::<String>,
            ),
            RouteInfo::new(
                "GET",
                "/users/:id",
                "get_user",
                None,
                None,
                None::<String>,
                None,
                Vec::new(),
                Vec::new(),
                None::<String>,
            ),
        ];
        let spec = build_openapi_spec("Test API", "1.0.0", &routes);

        let get_op = spec.paths.get("/users").unwrap().get.as_ref().unwrap();
        assert_eq!(get_op.operation_id.as_deref(), Some("list_users"));

        let post_op = spec.paths.get("/users").unwrap().post.as_ref().unwrap();
        assert_eq!(post_op.operation_id.as_deref(), Some("create_user"));

        let get_by_id = spec.paths.get("/users/{id}").unwrap().get.as_ref().unwrap();
        assert_eq!(get_by_id.operation_id.as_deref(), Some("get_user"));
    }

    #[test]
    #[should_panic(expected = "Duplicate operationId 'get_user'")]
    fn test_duplicate_operation_id_panics() {
        let routes = vec![
            RouteInfo::new(
                "GET",
                "/users/:id",
                "get_user",
                None,
                None,
                None::<String>,
                None,
                Vec::new(),
                Vec::new(),
                None::<String>,
            ),
            RouteInfo::new(
                "GET",
                "/posts/:id",
                "get_user",
                None,
                None,
                None::<String>,
                None,
                Vec::new(),
                Vec::new(),
                None::<String>,
            ),
        ];
        build_openapi_spec("Test API", "1.0.0", &routes);
    }

    #[test]
    #[should_panic(expected = "Duplicate operationId 'list'")]
    fn test_duplicate_operation_id_same_name_different_paths_panics() {
        let routes = vec![
            RouteInfo::new(
                "GET",
                "/users",
                "list",
                None,
                None,
                None::<String>,
                None,
                Vec::new(),
                Vec::new(),
                None::<String>,
            ),
            RouteInfo::new(
                "GET",
                "/posts",
                "list",
                None,
                None,
                None::<String>,
                None,
                Vec::new(),
                Vec::new(),
                None::<String>,
            ),
        ];
        build_openapi_spec("Test API", "1.0.0", &routes);
    }

    #[test]
    fn test_duplicate_operation_id_skips_internal_routes() {
        // Internal routes are skipped before the uniqueness check,
        // so duplicating an internal handler name with a public one is fine.
        let routes = vec![
            RouteInfo::new(
                "GET",
                "/__rapina/routes",
                "list",
                None,
                None,
                None::<String>,
                None,
                Vec::new(),
                Vec::new(),
                None::<String>,
            ),
            RouteInfo::new(
                "GET",
                "/posts",
                "list",
                None,
                None,
                None::<String>,
                None,
                Vec::new(),
                Vec::new(),
                None::<String>,
            ),
        ];
        // Should not panic — internal route is excluded from uniqueness tracking
        let spec = build_openapi_spec("Test API", "1.0.0", &routes);
        assert!(spec.paths.contains_key("/posts"));
        assert!(!spec.paths.contains_key("/__rapina/routes"));
    }
}