mirror of
https://github.com/LGUG2Z/komorebi.git
synced 2026-11-21 16:11:37 +01:00
Fix template rendering for tuples (arrays with prefixItems) that contain non-primitive types like $ref or anyOf, which were incorrectly detected as homogeneous tuples. Template Logic Fix: - Check if `item.type` and `first_type.type` are both defined before comparing - Treat items with $ref, anyOf, or missing type as heterogeneous - Apply fix in all three locations: render_type_badge, render_array_items_inline, and render_array_items macros Display Name Enhancement: - Strip trailing digits from ALL type names, not just wrapper types - Types like `DisplayFormat2` now display as `DisplayFormat` - Only adds `_display_name` when it differs from original name
489 lines
13 KiB
Rust
489 lines
13 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;
|
|
pub mod identifiers;
|
|
mod prepare;
|
|
|
|
pub use generator::Generator;
|
|
pub use identifiers::CSS;
|
|
pub use identifiers::IDS;
|
|
pub use identifiers::TYPE_CLASSES;
|
|
|
|
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"));
|
|
}
|
|
|
|
#[test]
|
|
fn test_tuple_with_ref_items() {
|
|
let schema: Schema = serde_json::from_str(
|
|
r##"{
|
|
"type": "object",
|
|
"properties": {
|
|
"coords": {
|
|
"type": "array",
|
|
"prefixItems": [
|
|
{ "$ref": "#/$defs/X" },
|
|
{ "$ref": "#/$defs/Y" }
|
|
]
|
|
}
|
|
},
|
|
"$defs": {
|
|
"X": { "type": "number" },
|
|
"Y": { "type": "number" }
|
|
}
|
|
}"##,
|
|
)
|
|
.unwrap();
|
|
|
|
let result = generate_html(&schema, &Options::default());
|
|
assert!(result.is_ok(), "Should handle $ref in prefixItems");
|
|
}
|
|
|
|
#[test]
|
|
fn test_tuple_with_mixed_items() {
|
|
let schema: Schema = serde_json::from_str(
|
|
r##"{
|
|
"type": "object",
|
|
"properties": {
|
|
"pair": {
|
|
"type": "array",
|
|
"prefixItems": [
|
|
{ "$ref": "#/$defs/Name" },
|
|
{ "type": "integer" }
|
|
]
|
|
}
|
|
},
|
|
"$defs": {
|
|
"Name": { "type": "string" }
|
|
}
|
|
}"##,
|
|
)
|
|
.unwrap();
|
|
|
|
let result = generate_html(&schema, &Options::default());
|
|
assert!(
|
|
result.is_ok(),
|
|
"Should handle mixed $ref and type in prefixItems"
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn test_tuple_with_anyof_items() {
|
|
let schema: Schema = serde_json::from_str(
|
|
r##"{
|
|
"type": "object",
|
|
"properties": {
|
|
"optional_pair": {
|
|
"type": "array",
|
|
"prefixItems": [
|
|
{ "type": "string" },
|
|
{ "anyOf": [{ "type": "number" }, { "type": "null" }] }
|
|
]
|
|
}
|
|
}
|
|
}"##,
|
|
)
|
|
.unwrap();
|
|
|
|
let result = generate_html(&schema, &Options::default());
|
|
assert!(result.is_ok(), "Should handle anyOf in prefixItems");
|
|
}
|
|
|
|
#[test]
|
|
fn test_homogeneous_tuple_still_works() {
|
|
let schema: Schema = serde_json::from_str(
|
|
r#"{
|
|
"type": "object",
|
|
"properties": {
|
|
"point": {
|
|
"type": "array",
|
|
"prefixItems": [
|
|
{ "type": "number" },
|
|
{ "type": "number" },
|
|
{ "type": "number" }
|
|
]
|
|
}
|
|
}
|
|
}"#,
|
|
)
|
|
.unwrap();
|
|
|
|
let result = generate_html(&schema, &Options::default());
|
|
assert!(result.is_ok());
|
|
let html = result.unwrap();
|
|
// Homogeneous tuples should show as "array float; 3" not "Tuple Items"
|
|
assert!(
|
|
html.contains("float; 3") || html.contains("number; 3"),
|
|
"Homogeneous tuple should display as [T; N] format"
|
|
);
|
|
}
|
|
}
|