///|
/// Describe a reusable component or route contract and collect its references.
pub(open) trait ToSchema {
fn to_schema(SchemaContext) -> @json.Json
}
///|
/// An empty request contract.
pub impl ToSchema for Unit with fn to_schema(_ctx) {
{}
}
///|
/// A type witness selecting the ToSchema implementation.
#warnings("-unused_type_variable")
pub(all) enum Tag[T] {
Tag
}
///|
/// Components collected while exporting one OpenAPI document.
struct SchemaContext {
components : Map[String, @json.Json]
references : Map[String, @json.Json?]
}
///|
fn SchemaContext::new(
components : @json.Json?,
) -> SchemaContext raise OpenApiError {
let components = if components is Some(Object(fields)) {
fields.copy()
} else if components is None {
Map([])
} else {
raise InvalidSchema("components must be an object")
}
{ components, references: Map([]), }
}
///|
/// Return a local component reference, generating its definition only once.
/// The tag selects the ToSchema implementation used for generation.
/// Mark the reference before generation so recursive components terminate.
pub fn[T : ToSchema] SchemaContext::ref(
self : SchemaContext,
name : String,
_tag : Tag[T],
) -> @json.Json {
let path = name
if !self.references.contains(path) {
let existing = if path.split("/").to_array()
is ["#", "components", section, name] &&
self.components.get(section.to_owned()) is Some(Object(definitions)) {
definitions.get(name.to_owned())
} else {
None
}
if existing is Some(existing) {
self.references[path] = Some(existing)
} else {
self.references[path] = None
self.references[path] = Some(T::to_schema(self))
}
}
{ "$ref": path }
}
///|
/// Resolve registered references for path normalization and HEAD responses.
fn SchemaContext::resolve(
self : SchemaContext,
schema : Json,
) -> Json raise OpenApiError {
let seen : Map[String, Unit] = Map([])
let siblings : Map[String, Json] = Map([])
let mut current = schema
while current is Object(fields) && fields.get("$ref") is Some(reference) {
guard reference is String(path) else {
raise InvalidSchema("Component reference must be a string")
}
guard !seen.contains(path) else {
raise InvalidSchema("Circular component reference: \{path}")
}
seen[path] = ()
for name, value in fields {
if name != "$ref" && !siblings.contains(name) {
siblings[name] = value
}
}
current = if self.references.get(path) is Some(Some(definition)) {
definition
} else if path.split("/").to_array() is ["#", "components", section, name] &&
self.components.get(section.to_owned()) is Some(Object(definitions)) &&
definitions.get(name.to_owned()) is Some(definition) {
definition
} else {
raise InvalidSchema("Unresolved component reference: \{path}")
}
}
if siblings.is_empty() {
current
} else {
guard current is Object(fields) else {
raise InvalidSchema("Referenced component must be an object")
}
let fields = fields.copy()
for name, value in siblings {
fields[name] = value
}
@json.Json::object(fields)
}
}
///|
fn SchemaContext::finish(
self : SchemaContext,
) -> @json.Json? raise OpenApiError {
for path, schema in self.references {
guard path.split("/").to_array() is ["#", "components", section, name] &&
section
is ("schemas"
| "responses"
| "parameters"
| "examples"
| "requestBodies"
| "headers"
| "securitySchemes"
| "links"
| "callbacks"
| "pathItems"
| "mediaTypes") &&
!name.is_empty() &&
name
.iter()
.all(c => c is ('a'..<='z' | 'A'..<='Z' | '0'..<='9' | '.' | '-' | '_')) else {
raise InvalidSchema("Expected a local component reference: \{path}")
}
guard schema is Some(schema) else {
raise InvalidSchema("Unfinished component: \{path}")
}
let section = section.to_owned()
let name = name.to_owned()
let definitions = if self.components.get(section) is Some(Object(fields)) {
fields.copy()
} else if !self.components.contains(section) {
Map([])
} else {
raise InvalidSchema("components.\{section} must be an object")
}
definitions[name] = schema
self.components[section] = @json.Json::object(definitions)
}
if self.components.is_empty() {
None
} else {
Some(@json.Json::object(self.components))
}
}