Files
komorebi/src/lib.rs
T
LGUG2Z c85edf242f feat(docgen): initial implementation of html doc generator
Implement a complete Rust library and CLI tool for generating self-contained
HTML documentation from schemars::Schema (JSON Schema) objects.

Core Features:
- Library API with `generate_html()` function and `Options` struct
- CLI binary accepting JSON Schema input files with optional title override
- Tera-based HTML templating with base template and reusable macros
- Markdown rendering for schema descriptions via pulldown-cmark
- Dark/light theme support following system preferences
- Searchable properties with instant search functionality
- Collapsible nested structures for complex schemas
- Responsive design for mobile, tablet, and desktop

Library Components:
- `generator.rs`: Main HTML generation logic with Tera template engine
- `prepare.rs`: Schema preprocessing for template rendering (1667 lines)
- `lib.rs`: Public API with SchemaExt trait for typed schema accessors
- `main.rs`: CLI interface using clap for argument parsing

Template System:
- `base.html`: Main HTML structure with header, sidebar, and content areas
- `macros.html`: Reusable Tera macros for rendering schema components
- `style.css`: Complete CSS with CSS variables for theming (955 lines)
2025-12-22 09:31:19 -08:00

380 lines
10 KiB
Rust

//! # 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<String>,
}
/// 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<String, Error> {
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<String, Value>>;
/// Get schema definitions ($defs)
fn definitions(&self) -> Option<&serde_json::Map<String, Value>>;
/// Get array items schema
fn items(&self) -> Option<&Value>;
/// Get anyOf schemas
fn any_of(&self) -> Option<&Vec<Value>>;
/// Get oneOf schemas
fn one_of(&self) -> Option<&Vec<Value>>;
/// Get allOf schemas
fn all_of(&self) -> Option<&Vec<Value>>;
/// Get enum values
fn enum_values(&self) -> Option<&Vec<Value>>;
/// 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<Value>>;
/// Get format constraint
fn format(&self) -> Option<&str>;
/// Get pattern constraint
fn pattern(&self) -> Option<&str>;
/// Get minimum constraint
fn minimum(&self) -> Option<f64>;
/// Get maximum constraint
fn maximum(&self) -> Option<f64>;
/// Get const value
fn const_value(&self) -> Option<&Value>;
/// Get pattern properties
fn pattern_properties(&self) -> Option<&serde_json::Map<String, Value>>;
/// Get additional properties schema
fn additional_properties(&self) -> Option<&Value>;
/// Get prefix items (tuple validation)
fn prefix_items(&self) -> Option<&Vec<Value>>;
/// Get min items constraint
fn min_items(&self) -> Option<u64>;
/// Get max items constraint
fn max_items(&self) -> Option<u64>;
/// 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<String, Value>> {
self.as_object()?.get("properties")?.as_object()
}
fn definitions(&self) -> Option<&serde_json::Map<String, Value>> {
self.as_object()?.get("$defs")?.as_object()
}
fn items(&self) -> Option<&Value> {
self.as_object()?.get("items")
}
fn any_of(&self) -> Option<&Vec<Value>> {
self.as_object()?.get("anyOf")?.as_array()
}
fn one_of(&self) -> Option<&Vec<Value>> {
self.as_object()?.get("oneOf")?.as_array()
}
fn all_of(&self) -> Option<&Vec<Value>> {
self.as_object()?.get("allOf")?.as_array()
}
fn enum_values(&self) -> Option<&Vec<Value>> {
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<Value>> {
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<f64> {
self.as_object()?.get("minimum")?.as_f64()
}
fn maximum(&self) -> Option<f64> {
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<String, Value>> {
self.as_object()?.get("patternProperties")?.as_object()
}
fn additional_properties(&self) -> Option<&Value> {
self.as_object()?.get("additionalProperties")
}
fn prefix_items(&self) -> Option<&Vec<Value>> {
self.as_object()?.get("prefixItems")?.as_array()
}
fn min_items(&self) -> Option<u64> {
self.as_object()?.get("minItems")?.as_u64()
}
fn max_items(&self) -> Option<u64> {
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<String, Value>> {
self.as_object()?.get("properties")?.as_object()
}
fn definitions(&self) -> Option<&serde_json::Map<String, Value>> {
self.as_object()?.get("$defs")?.as_object()
}
fn items(&self) -> Option<&Value> {
self.as_object()?.get("items")
}
fn any_of(&self) -> Option<&Vec<Value>> {
self.as_object()?.get("anyOf")?.as_array()
}
fn one_of(&self) -> Option<&Vec<Value>> {
self.as_object()?.get("oneOf")?.as_array()
}
fn all_of(&self) -> Option<&Vec<Value>> {
self.as_object()?.get("allOf")?.as_array()
}
fn enum_values(&self) -> Option<&Vec<Value>> {
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<Value>> {
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<f64> {
self.as_object()?.get("minimum")?.as_f64()
}
fn maximum(&self) -> Option<f64> {
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<String, Value>> {
self.as_object()?.get("patternProperties")?.as_object()
}
fn additional_properties(&self) -> Option<&Value> {
self.as_object()?.get("additionalProperties")
}
fn prefix_items(&self) -> Option<&Vec<Value>> {
self.as_object()?.get("prefixItems")?.as_array()
}
fn min_items(&self) -> Option<u64> {
self.as_object()?.get("minItems")?.as_u64()
}
fn max_items(&self) -> Option<u64> {
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"));
}
}