Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ https://github.com/oxidecomputer/dropshot/compare/v0.17.1\...HEAD[Full list of c

* The minimum supported Rust version is now 1.88.
* Replaced the unmaintained `rustls-pemfile` crate with the PEM support in `rustls-pki-types`. Failures to parse TLS certificates or private keys are now reported with the new `BuildError::PemError` variant rather than `BuildError::SystemError`.
* Fixed OpenAPI output for request and response bodies of type `Option<T>`, where `T` is a named schema type. Previously, these bodies were documented as a plain reference to `T` with `nullable` dropped, so generated clients failed to deserialize a `null` response. They're now documented as `{ "nullable": true, "allOf": [{ "$ref": ... }] }`, the same form already used for `Option<T>` struct fields. This changes the OpenAPI documents of APIs with such bodies.

== 0.17.1 (released 2026-06-02)

Expand Down
81 changes: 65 additions & 16 deletions dropshot/src/schema_util.rs
Original file line number Diff line number Diff line change
Expand Up @@ -374,21 +374,56 @@ fn j2oas_schema_object(
obj: &schemars::schema::SchemaObject,
) -> openapiv3::ReferenceOr<openapiv3::Schema> {
if let Some(reference) = &obj.reference {
return openapiv3::ReferenceOr::Reference {
reference: reference.clone(),
let reference =
openapiv3::ReferenceOr::Reference { reference: reference.clone() };

// schemars 0.8 has a bit of a footgun here: with
// `SchemaSettings::openapi3()`, `subschema_for::<Option<Foo>>()`
// returns:
//
// { "$ref": "#/components/schemas/Foo", "nullable": true }
//
// This is not permitted by OpenAPI 3.0. From
// https://spec.openapis.org/oas/v3.0.4.html#fixed-fields-19 (§4.7.23.1):
//
// > This object cannot be extended with additional properties, and any
// > properties added SHALL be ignored.
//
// So we need to rewrite schemas of this form to use an `allOf` wrapper
// instead.
//
// This is supposed to be handled by schemars's `RemoveRefSiblings`
// visitor
// (https://docs.rs/schemars/0.8.22/schemars/visit/struct.RemoveRefSiblings.html),
// but (for some reason) that visitor is only automatically run within
// `into_root_schema_for`, not within `subschema_for`. But using
// `into_root_schema_for` is a bit strange because there isn't really
// such a thing as a root schema in OpenAPI.
//
// An alternative would be to run the RemoveRefSiblings visitor here,
// but the only sibling property that's possible to produce in Dropshot
// is `nullable`.
if schema_object_is_nullable(obj) {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note that in this situation schemars should NOT be decorating a schema with extensions since it's not valid OpenAPI v3.0.x -- but it is.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep. Discussed privately in chat, and added a comment about this.

return openapiv3::ReferenceOr::Item(openapiv3::Schema {
schema_data: openapiv3::SchemaData {
nullable: true,
..Default::default()
},
schema_kind: openapiv3::SchemaKind::AllOf {
all_of: vec![reference],
},
});
} else {
return reference;
};
}

let kind = j2oas_schema_object_kind(obj);

let mut data = openapiv3::SchemaData::default();

if matches!(
&obj.extensions.get("nullable"),
Some(serde_json::Value::Bool(true))
) {
data.nullable = true;
}
let mut data = openapiv3::SchemaData {
nullable: schema_object_is_nullable(obj),
..Default::default()
};

if let Some(metadata) = &obj.metadata {
data.title.clone_from(&metadata.title);
Expand Down Expand Up @@ -420,6 +455,13 @@ fn j2oas_schema_object(
})
}

fn schema_object_is_nullable(obj: &schemars::schema::SchemaObject) -> bool {
matches!(
obj.extensions.get("nullable"),
Some(serde_json::Value::Bool(true))
)
}

fn j2oas_schema_object_kind(
obj: &schemars::schema::SchemaObject,
) -> openapiv3::SchemaKind {
Expand Down Expand Up @@ -1041,15 +1083,22 @@ mod test {
let settings = schemars::r#gen::SchemaSettings::openapi3();
let mut generator = schemars::r#gen::SchemaGenerator::new(settings);

// BUG: Currently, the fact that the type is nullable is dropped from
// the output, leading to the generated schema for Option<Foo> being
// the same as the one for Foo below.
// Ensure that for Option<Foo>, the result after conversion from JSON
// Schema to OpenAPI is a schema with nullable: true.
let schema = make_subschema_for::<Option<Foo>>(&mut generator);
assert_eq!(
j2oas_schema(None, &schema),
openapiv3::ReferenceOr::Reference {
reference: "#/components/schemas/Foo".to_string()
}
openapiv3::ReferenceOr::Item(openapiv3::Schema {
schema_data: openapiv3::SchemaData {
nullable: true,
..Default::default()
},
schema_kind: openapiv3::SchemaKind::AllOf {
all_of: vec![openapiv3::ReferenceOr::Reference {
reference: "#/components/schemas/Foo".to_string()
}],
},
})
);

let schema = make_subschema_for::<Foo>(&mut generator);
Expand Down
14 changes: 12 additions & 2 deletions dropshot/tests/test_openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -945,7 +945,12 @@
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoolStruct"
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/CoolStruct"
}
]
}
}
},
Expand All @@ -957,7 +962,12 @@
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoolStruct"
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/CoolStruct"
}
]
}
}
}
Expand Down
14 changes: 12 additions & 2 deletions dropshot/tests/test_openapi_fuller.json
Original file line number Diff line number Diff line change
Expand Up @@ -953,7 +953,12 @@
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoolStruct"
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/CoolStruct"
}
]
}
}
},
Expand All @@ -965,7 +970,12 @@
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CoolStruct"
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/CoolStruct"
}
]
}
}
}
Expand Down
Loading