bytedocs_rs/

lib.rs

//! # Bytedocs
//!
//! Bytedocs is a Rust alternative to Swagger for API documentation generation.
//! It automatically generates beautiful, interactive API documentation from your Rust web applications.
//!
//! ## Features
//!
//! - **Framework Support**: Works with Axum, Warp, Actix-web, and more
//! - **Beautiful UI**: Clean, responsive interface with dark/light mode
//! - **Authentication**: Built-in auth with session management and IP banning
//! - **AI Integration**: Optional AI-powered chat for API exploration
//! - **OpenAPI Compatible**: Generates standard OpenAPI 3.0.3 specifications
//! - **Fast**: Built with Rust for maximum performance
//!
//! ## Quick Start
//!
//! ```rust
//! use bytedocs_rs::{Bytedocs, Config};
//!
//! #[tokio::main]
//! async fn main() {
//!     let config = Config::default();
//!     let mut docs = Bytedocs::new(Some(config));
//!
//!     // Add your API routes
//!     docs.add_route("GET", "/users", None, Some("List all users"), None, None, None, None);
//!     docs.add_route("POST", "/users", None, Some("Create a new user"), None, None, None, None);
//!
//!     // Generate documentation
//!     docs.generate().unwrap();
//!
//!     println!("Documentation generated!");
//! }
//! ```

pub mod core;
pub mod ai;
pub mod parser;

pub use core::{
    Config, AuthConfig, UIConfig, APIInfo, Documentation, APIDocs,
    Endpoint, Parameter, RequestBody, Response, RouteInfo,
    load_config_from_env, validate_config, ByteDocsError, Result,
};

pub use ai::{AIConfig, AIFeatures, ChatRequest, ChatResponse, Client as AIClient};

pub use parser::{
    AxumParser, WarpParser, ActixWebParser, FrameworkParser,
    extract_path_params, generate_default_responses,
};

/// Main entry point for Bytedocs API documentation generation.
///
/// `Bytedocs` is the primary struct for creating and managing API documentation.
/// It wraps the internal `APIDocs` implementation and provides a user-friendly API.
pub struct Bytedocs {
    inner: APIDocs,
}

impl Bytedocs {
    /// Creates a new `Bytedocs` instance with the specified configuration.
    ///
    /// # Arguments
    ///
    /// * `config` - Optional configuration. If `None`, uses default configuration.
    ///
    /// # Example
    ///
    /// ```rust
    /// use bytedocs_rs::Bytedocs;
    ///
    /// let docs = Bytedocs::new(None);
    /// ```
    pub fn new(config: Option<Config>) -> Self {
        Self {
            inner: APIDocs::new(config),
        }
    }

    /// Creates a `Bytedocs` instance from environment variables.
    ///
    /// Reads configuration from environment variables and validates it.
    ///
    /// # Errors
    ///
    /// Returns an error if environment variables are invalid or configuration validation fails.
    pub fn from_env() -> Result<Self> {
        let config = load_config_from_env(None)
            .map_err(|e| ByteDocsError::Environment(e.to_string()))?;
        validate_config(&config)
            .map_err(|e| ByteDocsError::Config(e.to_string()))?;
        Ok(Self::new(Some(config)))
    }

    /// Creates a `Bytedocs` instance from a `.env` file.
    ///
    /// # Arguments
    ///
    /// * `env_file` - Path to the environment file to load
    ///
    /// # Errors
    ///
    /// Returns an error if the file path is empty, file cannot be read,
    /// or configuration validation fails.
    pub fn from_env_file(env_file: &str) -> Result<Self> {
        if env_file.is_empty() {
            return Err(ByteDocsError::InvalidInput("Environment file path cannot be empty".to_string()));
        }

        let config = load_config_from_env(Some(env_file))
            .map_err(|e| ByteDocsError::Environment(e.to_string()))?;
        validate_config(&config)
            .map_err(|e| ByteDocsError::Config(e.to_string()))?;
        Ok(Self::new(Some(config)))
    }

    /// Adds a new API route to the documentation.
    ///
    /// # Arguments
    ///
    /// * `method` - HTTP method (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
    /// * `path` - API endpoint path (must start with '/')
    /// * `handler` - Optional handler function (for framework integration)
    /// * `summary` - Optional short description of the endpoint
    /// * `description` - Optional detailed description
    /// * `parameters` - Optional list of parameters
    /// * `request_body` - Optional request body specification
    /// * `responses` - Optional response specifications
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - Method is empty or invalid
    /// - Path is empty or doesn't start with '/'
    /// - Path format is invalid
    #[allow(clippy::too_many_arguments)]
    pub fn add_route(
        &mut self,
        method: &str,
        path: &str,
        handler: Option<Box<dyn std::any::Any + Send + Sync>>,
        summary: Option<&str>,
        description: Option<&str>,
        parameters: Option<Vec<Parameter>>,
        request_body: Option<RequestBody>,
        responses: Option<std::collections::HashMap<String, Response>>,
    ) -> Result<()> {
        if method.is_empty() {
            return Err(ByteDocsError::InvalidInput("HTTP method cannot be empty".to_string()));
        }

        if path.is_empty() {
            return Err(ByteDocsError::InvalidInput("Path cannot be empty".to_string()));
        }

        if !path.starts_with('/') {
            return Err(ByteDocsError::InvalidInput("Path must start with '/'".to_string()));
        }

        // Check for invalid paths like "//" or paths with only whitespace
        let trimmed_path = path.trim();
        if trimmed_path.is_empty() || trimmed_path == "//" {
            return Err(ByteDocsError::InvalidInput("Invalid path format".to_string()));
        }

        let valid_methods = ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"];
        if !valid_methods.contains(&method.to_uppercase().as_str()) {
            return Err(ByteDocsError::InvalidInput(format!("Invalid HTTP method: {}", method)));
        }

        let sanitized_method = method.trim().to_uppercase();
        let sanitized_path = path.trim().to_string();
        let sanitized_summary = summary.map(|s| s.trim().to_string());
        let sanitized_description = description.map(|s| s.trim().to_string());

        self.inner.add_route(
            &sanitized_method,
            &sanitized_path,
            handler.unwrap_or_else(|| Box::new(())),
            sanitized_summary,
            sanitized_description,
            parameters,
            request_body,
            responses,
        );

        Ok(())
    }

    /// Adds multiple routes at once.
    ///
    /// # Arguments
    ///
    /// * `routes` - Vector of `RouteInfo` structs to add
    pub fn add_routes(&mut self, routes: Vec<RouteInfo>) {
        for route in routes {
            self.inner.add_route_info(route);
        }
    }

    /// Automatically detects and extracts Axum routes from source files.
    ///
    /// # Arguments
    ///
    /// * `source_paths` - Array of source file paths to scan
    ///
    /// # Errors
    ///
    /// Returns an error if source paths are empty or route detection fails.
    pub fn auto_detect_axum_routes(&mut self, source_paths: &[&str]) -> Result<()> {
        if source_paths.is_empty() {
            return Err(ByteDocsError::InvalidInput("Source paths cannot be empty".to_string()));
        }

        let parser = parser::AxumParser::new();

        for source_path in source_paths {
            if source_path.is_empty() {
                return Err(ByteDocsError::InvalidInput("Source path cannot be empty".to_string()));
            }

            let routes = parser.auto_detect_routes(source_path)
                .map_err(|e| ByteDocsError::RouteDetection(e.to_string()))?;
            self.add_routes(routes);
        }

        Ok(())
    }

    /// Convenience method to auto-detect routes from `src/main.rs`.
    ///
    /// # Errors
    ///
    /// Returns an error if route detection fails.
    pub fn auto_detect_from_main(&mut self) -> Result<()> {
        self.auto_detect_axum_routes(&["src/main.rs"])
    }

    /// Generates the API documentation.
    ///
    /// This must be called after adding all routes and before serving the documentation.
    ///
    /// # Errors
    ///
    /// Returns an error if documentation generation fails.
    pub fn generate(&mut self) -> Result<()> {
        self.inner.generate()
            .map_err(|e| ByteDocsError::Server(e.to_string()))
    }

    /// Returns a reference to the generated documentation.
    pub fn documentation(&self) -> &Documentation {
        self.inner.get_documentation()
    }

    /// Returns a reference to the configuration.
    pub fn config(&self) -> &Config {
        self.inner.get_config()
    }

    /// Returns the OpenAPI specification as JSON.
    ///
    /// # Errors
    ///
    /// Returns an error if JSON generation fails.
    pub async fn openapi_json(&mut self) -> Result<serde_json::Value> {
        self.inner.get_openapi_json().await
            .map_err(|e| ByteDocsError::Server(e.to_string()))
    }

    /// Returns the OpenAPI specification as YAML.
    ///
    /// # Errors
    ///
    /// Returns an error if YAML generation fails.
    pub async fn openapi_yaml(&mut self) -> Result<String> {
        self.inner.get_openapi_yaml().await
            .map_err(|e| ByteDocsError::Server(e.to_string()))
    }

    /// Returns an Axum router with all documentation routes configured.
    ///
    /// This can be merged with your application's existing router.
    pub fn router(&self) -> axum::Router {
        self.inner.router()
    }

    /// Starts the documentation server on the specified address.
    ///
    /// # Arguments
    ///
    /// * `addr` - The address to bind to (e.g., "0.0.0.0:8813")
    ///
    /// # Errors
    ///
    /// Returns an error if the address is empty or the server fails to start.
    pub async fn serve(&self, addr: &str) -> Result<()> {
        if addr.is_empty() {
            return Err(ByteDocsError::InvalidInput("Address cannot be empty".to_string()));
        }

        let app = self.router();
        let listener = tokio::net::TcpListener::bind(addr)
            .await
            .map_err(|e| ByteDocsError::Server(format!("Failed to bind to {}: {}", addr, e)))?;


        axum::serve(listener, app)
            .await
            .map_err(|e| ByteDocsError::Server(format!("Server error: {}", e)))?;
        Ok(())
    }
}


/// Creates a `Bytedocs` instance configured for Axum framework.
///
/// This is a convenience function equivalent to `Bytedocs::new()`.
///
/// # Arguments
///
/// * `config` - Optional configuration
pub fn axum_docs(config: Option<Config>) -> Bytedocs {
    Bytedocs::new(config)
}

/// Creates a `Bytedocs` instance configured for Warp framework.
///
/// This is a convenience function equivalent to `Bytedocs::new()`.
///
/// # Arguments
///
/// * `config` - Optional configuration
pub fn warp_docs(config: Option<Config>) -> Bytedocs {
    Bytedocs::new(config)
}

/// Creates a `Bytedocs` instance configured for Actix-web framework.
///
/// This is a convenience function equivalent to `Bytedocs::new()`.
///
/// # Arguments
///
/// * `config` - Optional configuration
pub fn actix_docs(config: Option<Config>) -> Bytedocs {
    Bytedocs::new(config)
}

/// Builder pattern for creating `Bytedocs` instances with custom configuration.
///
/// Provides a fluent API for configuring Bytedocs before instantiation.
pub struct ByteDocsBuilder {
    config: Config,
}

impl ByteDocsBuilder {
    /// Creates a new builder with default configuration.
    pub fn new() -> Self {
        Self {
            config: Config::default(),
        }
    }

    /// Sets the API documentation title.
    pub fn title(mut self, title: &str) -> Self {
        self.config.title = title.to_string();
        self
    }

    /// Sets the API version.
    pub fn version(mut self, version: &str) -> Self {
        self.config.version = version.to_string();
        self
    }

    /// Sets the API description.
    pub fn description(mut self, description: &str) -> Self {
        self.config.description = description.to_string();
        self
    }

    /// Sets the base URL for the API.
    pub fn base_url(mut self, base_url: &str) -> Self {
        self.config.base_url = base_url.to_string();
        self
    }

    /// Sets the path where documentation will be served.
    pub fn docs_path(mut self, docs_path: &str) -> Self {
        self.config.docs_path = docs_path.to_string();
        self
    }

    /// Enables authentication with the specified configuration.
    pub fn with_auth(mut self, auth_config: AuthConfig) -> Self {
        self.config.auth_config = Some(auth_config);
        self
    }

    /// Enables AI features with the specified configuration.
    pub fn with_ai(mut self, ai_config: AIConfig) -> Self {
        self.config.ai_config = Some(ai_config);
        self
    }

    /// Builds the `Bytedocs` instance with the configured settings.
    pub fn build(self) -> Bytedocs {
        Bytedocs::new(Some(self.config))
    }
}

impl Default for ByteDocsBuilder {
    fn default() -> Self {
        Self::new()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_bytedocs_creation() {
        let docs = Bytedocs::new(None);
        assert_eq!(docs.config().title, "API Documentation");
    }

    #[test]
    fn test_builder_pattern() {
        let docs = ByteDocsBuilder::new()
            .title("My API")
            .version("1.0.0")
            .description("Test API")
            .build();

        assert_eq!(docs.config().title, "My API");
        assert_eq!(docs.config().version, "1.0.0");
        assert_eq!(docs.config().description, "Test API");
    }

    #[tokio::test]
    async fn test_route_addition() {
        let mut docs = Bytedocs::new(None);
        let _ = docs.add_route("GET", "/users", None, Some("List users"), None, None, None, None);

        docs.generate().unwrap();
        let documentation = docs.documentation();
        assert!(!documentation.endpoints.is_empty());
    }
}