blob: a0d36bb70b6ab3fb780e2ca5032fe129ea8f9985 [file]
// Copyright 2024 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use anyhow::{Result, anyhow, bail};
use schemars::Schema;
use serde::Serialize;
use serde_json::Value;
use std::collections::{BTreeMap, BTreeSet};
/// The data that describes the entire serde user interface.
/// This is extracted from a json schema.
#[derive(Debug, Serialize, PartialEq)]
pub struct AllData {
/// The base url path to append to all links.
pub url_path: String,
/// The root data type.
pub root: String,
/// All data types, including the root.
/// This contains the data for each struct/enum/etc.
pub data_types: BTreeMap<String, DataType>,
}
impl AllData {
/// Construct AllData from a root json schema.
pub fn from_root_schema(url_path: &String, root_schema: &Schema) -> Result<Self> {
let url_path = url_path.clone();
let mut data_types = BTreeMap::new();
let root_type = DataType::from_root_schema(root_schema)?;
data_types.insert(root_type.rust_type.clone(), root_type.clone());
let defs = root_schema
.get("$defs")
.or_else(|| root_schema.get("definitions"))
.and_then(|v| v.as_object());
if let Some(defs) = defs {
for (rust_type, schema_val) in defs {
let schema: &Schema = schema_val.try_into()?;
let child = DataType::from_schema(rust_type.clone(), schema)?;
data_types.insert(child.rust_type.clone(), child);
}
}
Ok(Self { url_path, root: root_type.rust_type, data_types })
}
}
/// Data for a single struct/enum/etc.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Serialize)]
pub struct DataType {
/// The rust type.
pub rust_type: String,
/// The rust doc-comment.
pub description: String,
#[serde(flatten)]
pub inner: DataTypeInner,
}
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Serialize)]
#[serde(untagged)]
pub enum DataTypeInner {
Primitive(PrimitiveDataType),
Enum(EnumDataType),
Struct(StructDataType),
}
/// A primitive data type, such as a u8 or String.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Serialize)]
pub struct PrimitiveDataType {
/// The data type name.
pub data_type: String,
}
/// An enum data type.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Serialize)]
pub struct EnumDataType {
/// The variants of the enum.
/// Note that this does not currently support complex enums or descriptions.
/// The schemars crate does not populate descriptions for enums.
pub variants: BTreeSet<String>,
}
/// A struct data type.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Serialize)]
pub struct StructDataType {
/// The fields of the struct.
pub fields: BTreeSet<StructFieldData>,
}
/// A single struct field, which should point to a sub-data-type.
#[derive(Debug, Clone, Eq, Serialize)]
pub struct StructFieldData {
/// The name of the field.
pub field_name: String,
/// The doc-comment for the field.
pub description: String,
/// The default value of the field.
#[serde(skip_serializing_if = "Option::is_none")]
pub default: Option<Value>,
/// The data type of the field.
#[serde(flatten)]
pub data_type: StructFieldType,
}
/// The type of a single struct field.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Serialize)]
#[serde(tag = "kind", rename_all = "lowercase")]
pub enum StructFieldType {
Primitive { data_type: String },
Custom { data_type: String },
}
impl PartialEq for StructFieldData {
fn eq(&self, other: &Self) -> bool {
self.field_name == other.field_name
}
}
impl Ord for StructFieldData {
fn cmp(&self, other: &Self) -> std::cmp::Ordering {
other.field_name.cmp(&self.field_name)
}
}
impl PartialOrd for StructFieldData {
fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
Some(self.cmp(&other))
}
}
fn strip_ref_prefix(reference: &str) -> String {
reference
.strip_prefix("#/$defs/")
.or_else(|| reference.strip_prefix("#/definitions/"))
.or_else(|| reference.strip_prefix("#/"))
.unwrap_or(reference)
.to_string()
}
fn extract_unit_variants_from_one_of(one_of: &[Value]) -> Option<BTreeSet<String>> {
let mut variants = BTreeSet::new();
for item in one_of {
let obj = item.as_object()?;
if obj.get("type").and_then(|v| v.as_str()) != Some("string") {
return None;
}
if let Some(const_val) = obj.get("const") {
variants.insert(const_val.to_string());
} else if let Some(enum_vals) = obj.get("enum").and_then(|v| v.as_array()) {
for v in enum_vals {
variants.insert(v.to_string());
}
} else {
return None;
}
}
if variants.is_empty() { None } else { Some(variants) }
}
impl DataType {
/// Construct a DataType from a root schema object.
fn from_root_schema(root_schema: &Schema) -> Result<Self> {
let rust_type = root_schema
.get("title")
.and_then(|v| v.as_str())
.ok_or_else(|| anyhow!("missing title from root"))?
.to_string();
let description = root_schema
.get("description")
.and_then(|v| v.as_str())
.ok_or_else(|| anyhow!("missing description from {}", rust_type))?
.to_string();
Self::from_schema_object(rust_type, description, root_schema)
}
/// Construct a DataType from a non-root schema object.
fn from_schema(rust_type: String, schema: &Schema) -> Result<Self> {
let description = schema
.get("description")
.and_then(|v| v.as_str())
.map(|s| s.to_string())
.unwrap_or_else(|| "no description".to_string());
Self::from_schema_object(rust_type, description, schema)
}
/// Construct a DataType from a generic schema object.
fn from_schema_object(rust_type: String, description: String, schema: &Schema) -> Result<Self> {
// The description may be modified to add an error message.
let mut description = description;
// An enum.
let inner = if let Some(enum_values) = schema.get("enum").and_then(|v| v.as_array()) {
let variants = enum_values.iter().map(|v| v.to_string()).collect();
DataTypeInner::Enum(EnumDataType { variants })
} else if let Some(variants) = schema
.get("oneOf")
.and_then(|v| v.as_array())
.and_then(|arr| extract_unit_variants_from_one_of(arr))
{
DataTypeInner::Enum(EnumDataType { variants })
}
// An enum with variants of different types.
// TODO(b/332348955): Support this properly.
// TODO(b/436293725): Support comments on enum variants.
else if schema.get("oneOf").is_some()
|| schema.get("anyOf").is_some()
|| schema.get("allOf").is_some()
{
let error_message = format!(
"Failed to generate docs for complex {} enum: b/332348955 or b/436293725",
rust_type
);
description = format!("{}\n\n{}", error_message, description);
// println!("{}", error_message);
DataTypeInner::Enum(EnumDataType { variants: BTreeSet::new() })
}
// A struct.
else if let Some(properties) = schema.get("properties").and_then(|v| v.as_object()) {
let fields = properties
.iter()
.map(|(field_name, p)| {
let object: &Schema = p.try_into()?;
let data_type = if let Some(format) =
object.get("format").and_then(|v| v.as_str())
{
StructFieldType::Primitive { data_type: format.to_string() }
} else if let Some(reference) = object.get("$ref").and_then(|v| v.as_str()) {
StructFieldType::Custom { data_type: strip_ref_prefix(reference) }
} else if let Some(single_or_vec) = object.get("type") {
StructFieldType::Primitive {
data_type: single_or_vec_to_string(single_or_vec)?,
}
} else {
let mut subobjects = Vec::<&Value>::new();
if let Some(subs) = object.get("allOf").and_then(|v| v.as_array()) {
subobjects.extend(subs.iter());
}
if let Some(subs) = object.get("anyOf").and_then(|v| v.as_array()) {
subobjects.extend(subs.iter());
}
if let Some(subs) = object.get("oneOf").and_then(|v| v.as_array()) {
subobjects.extend(subs.iter());
}
if subobjects.is_empty() {
bail!("Missing subschemas for {}", rust_type);
}
let subobject = subobjects
.first()
.ok_or_else(|| anyhow!("Missing subobject for {}", rust_type))?;
let reference =
subobject.get("$ref").and_then(|v| v.as_str()).ok_or_else(|| {
anyhow!("Missing reference for field in {}", rust_type)
})?;
StructFieldType::Custom { data_type: strip_ref_prefix(reference) }
};
let description = object
.get("description")
.and_then(|v| v.as_str())
.unwrap_or("")
.to_string();
let default = object.get("default").cloned();
Ok(StructFieldData {
field_name: field_name.clone(),
data_type,
description,
default,
})
})
.collect::<Result<BTreeSet<StructFieldData>>>()?;
DataTypeInner::Struct(StructDataType { fields })
} else if schema.get("type").and_then(|v| v.as_str()) == Some("object")
&& (schema.get("additionalProperties").is_some()
|| schema.get("patternProperties").is_some())
{
DataTypeInner::Struct(StructDataType { fields: BTreeSet::new() })
}
// A primitive wrapped by a type.
// e.g. ImageName(String)
else if let Some(single_or_vec) = schema.get("type") {
let data_type = single_or_vec_to_string(single_or_vec)?;
DataTypeInner::Primitive(PrimitiveDataType { data_type })
}
// Unsupported.
else {
anyhow::bail!("Unsupported schema type for {}", rust_type);
};
Ok(Self { rust_type, description, inner })
}
}
/// Convert a type Value (string or array of strings) to a user-friendly String.
fn single_or_vec_to_string(single_or_vec: &Value) -> Result<String> {
match single_or_vec {
Value::String(t) => Ok(instance_type_to_string(t)?),
Value::Array(v) => {
let t = v
.first()
.and_then(|v| v.as_str())
.ok_or_else(|| anyhow!("Missing instance type"))?;
Ok(format!("[{}]", instance_type_to_string(t)?))
}
_ => bail!("unsupported type value"),
}
}
/// Convert a schema InstanceType string to a user-friendly String.
fn instance_type_to_string(instance_type: &str) -> Result<String> {
let s = match instance_type {
"boolean" => "bool",
"array" => "vector",
"string" => "string",
"integer" | "number" => "integer",
"object" => "object",
_ => bail!("unsupported type"),
}
.to_string();
Ok(s)
}
#[cfg(test)]
mod tests {
use super::{
AllData, DataType, DataTypeInner, EnumDataType, StructDataType, StructFieldData,
StructFieldType, single_or_vec_to_string,
};
use pretty_assertions::assert_eq;
use schemars::JsonSchema;
use schemars::generate::SchemaSettings;
use serde::Serialize;
use serde_json::json;
use std::collections::{BTreeMap, BTreeSet};
/// Mandatory description on root struct.
#[derive(Serialize, JsonSchema)]
struct RootStruct {
/// Primitives should work
field_1: u8,
/// Nested enums should work
field_2: MyEnum,
/// Vectors should work
field_3: Vec<String>,
/// Nested structs should work
field_4: MyStruct,
}
/// Really cool enum.
#[allow(dead_code)]
#[derive(Serialize, JsonSchema)]
enum MyEnum {
Variant1,
#[serde(rename = "variant_2")]
Variant2,
}
/// Really cool struct.
#[derive(Serialize, JsonSchema)]
struct MyStruct {
/// Booleans should work
field_5: bool,
}
#[test]
fn test() {
let settings = SchemaSettings::default();
let generator = settings.into_generator();
let root_schema = generator.into_root_schema_for::<RootStruct>();
let all_data = AllData::from_root_schema(&"url_path".into(), &root_schema).unwrap();
let expected = AllData {
url_path: "url_path".into(),
root: "RootStruct".into(),
data_types: BTreeMap::from([
(
"RootStruct".into(),
DataType {
rust_type: "RootStruct".into(),
description: "Mandatory description on root struct.".into(),
inner: DataTypeInner::Struct(StructDataType {
fields: BTreeSet::from([
StructFieldData {
field_name: "field_1".into(),
description: "Primitives should work".into(),
default: None,
data_type: StructFieldType::Primitive {
data_type: "uint8".into(),
},
},
StructFieldData {
field_name: "field_2".into(),
description: "Nested enums should work".into(),
default: None,
data_type: StructFieldType::Custom {
data_type: "MyEnum".into(),
},
},
StructFieldData {
field_name: "field_3".into(),
description: "Vectors should work".into(),
default: None,
data_type: StructFieldType::Primitive {
data_type: "vector".into(),
},
},
StructFieldData {
field_name: "field_4".into(),
description: "Nested structs should work".into(),
default: None,
data_type: StructFieldType::Custom {
data_type: "MyStruct".into(),
},
},
]),
}),
},
),
(
"MyEnum".into(),
DataType {
rust_type: "MyEnum".into(),
description: "Really cool enum.".into(),
inner: DataTypeInner::Enum(EnumDataType {
variants: BTreeSet::from([
"\"Variant1\"".into(),
"\"variant_2\"".into(),
]),
}),
},
),
(
"MyStruct".into(),
DataType {
rust_type: "MyStruct".into(),
description: "Really cool struct.".into(),
inner: DataTypeInner::Struct(StructDataType {
fields: BTreeSet::from([StructFieldData {
field_name: "field_5".into(),
description: "Booleans should work".into(),
default: None,
data_type: StructFieldType::Primitive {
data_type: "boolean".into(),
},
}]),
}),
},
),
]),
};
assert_eq!(expected, all_data);
}
#[test]
fn test_instance_type_to_string() {
let s = single_or_vec_to_string(&json!("integer")).unwrap();
assert_eq!("integer", &s);
let s = single_or_vec_to_string(&json!("boolean")).unwrap();
assert_eq!("bool", &s);
let s = single_or_vec_to_string(&json!(["boolean"])).unwrap();
assert_eq!("[bool]", &s);
}
}