//! # schemars-docgen //! //! Generate HTML documentation from `schemars::Schema` objects. //! //! This library takes a JSON Schema (as produced by schemars) and generates //! a self-contained HTML documentation page with: //! //! - Responsive design (mobile, tablet, desktop) //! - Dark/light mode following system preference //! - Searchable properties //! - Collapsible nested structures //! - Markdown rendering for descriptions //! //! ## Usage //! //! ```rust,no_run //! use schemars::schema_for; //! use schemars_docgen::{generate_html, Options}; //! //! #[derive(schemars::JsonSchema)] //! struct MyConfig { //! /// The name of the configuration //! name: String, //! } //! //! let schema = schema_for!(MyConfig); //! let options = Options::default(); //! let html = generate_html(&schema, &options).unwrap(); //! ``` mod generator; mod prepare; pub use generator::Generator; use schemars::Schema; use serde_json::Value; /// Options for HTML generation #[derive(Debug, Clone, Default)] pub struct Options { /// Override the schema title pub title_override: Option, } /// Error type for documentation generation #[derive(Debug, thiserror::Error)] pub enum Error { #[error("Template error: {0}")] Template(#[from] tera::Error), #[error("JSON error: {0}")] Json(#[from] serde_json::Error), } /// Generate HTML documentation from a schema /// /// This is the main entry point for the library. It takes a `schemars::Schema` /// and returns a self-contained HTML string. pub fn generate_html(schema: &Schema, options: &Options) -> Result { let generator = Generator::new()?; generator.generate(schema, options) } /// Extension trait for convenient access to common schema properties /// /// Since `schemars::Schema` is a wrapper around `serde_json::Value`, /// this trait provides typed accessors for standard JSON Schema keywords. pub trait SchemaExt { /// Get the schema title fn title(&self) -> Option<&str>; /// Get the schema description fn description(&self) -> Option<&str>; /// Get the schema type (can be a string or array of strings) fn schema_type(&self) -> Option<&Value>; /// Get object properties fn properties(&self) -> Option<&serde_json::Map>; /// Get schema definitions ($defs) fn definitions(&self) -> Option<&serde_json::Map>; /// Get array items schema fn items(&self) -> Option<&Value>; /// Get anyOf schemas fn any_of(&self) -> Option<&Vec>; /// Get oneOf schemas fn one_of(&self) -> Option<&Vec>; /// Get allOf schemas fn all_of(&self) -> Option<&Vec>; /// Get enum values fn enum_values(&self) -> Option<&Vec>; /// Get $ref target fn ref_target(&self) -> Option<&str>; /// Get default value fn default_value(&self) -> Option<&Value>; /// Get required fields fn required_fields(&self) -> Option<&Vec>; /// Get format constraint fn format(&self) -> Option<&str>; /// Get pattern constraint fn pattern(&self) -> Option<&str>; /// Get minimum constraint fn minimum(&self) -> Option; /// Get maximum constraint fn maximum(&self) -> Option; /// Get const value fn const_value(&self) -> Option<&Value>; /// Get pattern properties fn pattern_properties(&self) -> Option<&serde_json::Map>; /// Get additional properties schema fn additional_properties(&self) -> Option<&Value>; /// Get prefix items (tuple validation) fn prefix_items(&self) -> Option<&Vec>; /// Get min items constraint fn min_items(&self) -> Option; /// Get max items constraint fn max_items(&self) -> Option; /// Check if deprecated fn is_deprecated(&self) -> bool; } impl SchemaExt for Schema { fn title(&self) -> Option<&str> { self.as_object()?.get("title")?.as_str() } fn description(&self) -> Option<&str> { self.as_object()?.get("description")?.as_str() } fn schema_type(&self) -> Option<&Value> { self.as_object()?.get("type") } fn properties(&self) -> Option<&serde_json::Map> { self.as_object()?.get("properties")?.as_object() } fn definitions(&self) -> Option<&serde_json::Map> { self.as_object()?.get("$defs")?.as_object() } fn items(&self) -> Option<&Value> { self.as_object()?.get("items") } fn any_of(&self) -> Option<&Vec> { self.as_object()?.get("anyOf")?.as_array() } fn one_of(&self) -> Option<&Vec> { self.as_object()?.get("oneOf")?.as_array() } fn all_of(&self) -> Option<&Vec> { self.as_object()?.get("allOf")?.as_array() } fn enum_values(&self) -> Option<&Vec> { self.as_object()?.get("enum")?.as_array() } fn ref_target(&self) -> Option<&str> { self.as_object()?.get("$ref")?.as_str() } fn default_value(&self) -> Option<&Value> { self.as_object()?.get("default") } fn required_fields(&self) -> Option<&Vec> { self.as_object()?.get("required")?.as_array() } fn format(&self) -> Option<&str> { self.as_object()?.get("format")?.as_str() } fn pattern(&self) -> Option<&str> { self.as_object()?.get("pattern")?.as_str() } fn minimum(&self) -> Option { self.as_object()?.get("minimum")?.as_f64() } fn maximum(&self) -> Option { self.as_object()?.get("maximum")?.as_f64() } fn const_value(&self) -> Option<&Value> { self.as_object()?.get("const") } fn pattern_properties(&self) -> Option<&serde_json::Map> { self.as_object()?.get("patternProperties")?.as_object() } fn additional_properties(&self) -> Option<&Value> { self.as_object()?.get("additionalProperties") } fn prefix_items(&self) -> Option<&Vec> { self.as_object()?.get("prefixItems")?.as_array() } fn min_items(&self) -> Option { self.as_object()?.get("minItems")?.as_u64() } fn max_items(&self) -> Option { self.as_object()?.get("maxItems")?.as_u64() } fn is_deprecated(&self) -> bool { self.as_object() .and_then(|o| o.get("deprecated")) .and_then(|v| v.as_bool()) .unwrap_or(false) } } /// Extension trait for Value to use the same accessors impl SchemaExt for Value { fn title(&self) -> Option<&str> { self.as_object()?.get("title")?.as_str() } fn description(&self) -> Option<&str> { self.as_object()?.get("description")?.as_str() } fn schema_type(&self) -> Option<&Value> { self.as_object()?.get("type") } fn properties(&self) -> Option<&serde_json::Map> { self.as_object()?.get("properties")?.as_object() } fn definitions(&self) -> Option<&serde_json::Map> { self.as_object()?.get("$defs")?.as_object() } fn items(&self) -> Option<&Value> { self.as_object()?.get("items") } fn any_of(&self) -> Option<&Vec> { self.as_object()?.get("anyOf")?.as_array() } fn one_of(&self) -> Option<&Vec> { self.as_object()?.get("oneOf")?.as_array() } fn all_of(&self) -> Option<&Vec> { self.as_object()?.get("allOf")?.as_array() } fn enum_values(&self) -> Option<&Vec> { self.as_object()?.get("enum")?.as_array() } fn ref_target(&self) -> Option<&str> { self.as_object()?.get("$ref")?.as_str() } fn default_value(&self) -> Option<&Value> { self.as_object()?.get("default") } fn required_fields(&self) -> Option<&Vec> { self.as_object()?.get("required")?.as_array() } fn format(&self) -> Option<&str> { self.as_object()?.get("format")?.as_str() } fn pattern(&self) -> Option<&str> { self.as_object()?.get("pattern")?.as_str() } fn minimum(&self) -> Option { self.as_object()?.get("minimum")?.as_f64() } fn maximum(&self) -> Option { self.as_object()?.get("maximum")?.as_f64() } fn const_value(&self) -> Option<&Value> { self.as_object()?.get("const") } fn pattern_properties(&self) -> Option<&serde_json::Map> { self.as_object()?.get("patternProperties")?.as_object() } fn additional_properties(&self) -> Option<&Value> { self.as_object()?.get("additionalProperties") } fn prefix_items(&self) -> Option<&Vec> { self.as_object()?.get("prefixItems")?.as_array() } fn min_items(&self) -> Option { self.as_object()?.get("minItems")?.as_u64() } fn max_items(&self) -> Option { self.as_object()?.get("maxItems")?.as_u64() } fn is_deprecated(&self) -> bool { self.as_object() .and_then(|o| o.get("deprecated")) .and_then(|v| v.as_bool()) .unwrap_or(false) } } #[cfg(test)] mod tests { use super::*; #[test] fn test_schema_ext_title() { let schema: Schema = serde_json::from_str(r#"{"title": "Test Schema", "type": "object"}"#).unwrap(); assert_eq!(schema.title(), Some("Test Schema")); } #[test] fn test_schema_ext_description() { let schema: Schema = serde_json::from_str(r#"{"description": "A test description"}"#).unwrap(); assert_eq!(schema.description(), Some("A test description")); } #[test] fn test_schema_ext_ref() { let schema: Schema = serde_json::from_str(r##"{"$ref": "#/$defs/MyType"}"##).unwrap(); assert_eq!(schema.ref_target(), Some("#/$defs/MyType")); } #[test] fn test_schema_ext_properties() { let schema: Schema = serde_json::from_str( r#"{"type": "object", "properties": {"name": {"type": "string"}}}"#, ) .unwrap(); let props = schema.properties().unwrap(); assert!(props.contains_key("name")); } }