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 .changepacks/changepack_log_request-view-naming.json
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{"changes":{"crates/vespera/Cargo.toml":"Patch","crates/vespera_core/Cargo.toml":"Patch","crates/vespera_macro/Cargo.toml":"Patch","crates/vespera_inprocess/Cargo.toml":"Patch","crates/vespera_jni/Cargo.toml":"Patch","libs/vespera-bridge/build.gradle.kts":"Patch","libs/vespera-bridge-gradle-plugin/build.gradle.kts":"Patch"},"note":"vespera_macro request views: a type whose request view differs but that only request bodies reach (no response, directly or through another type) keeps its own component name — {Name} is its request view and no {Name}Input or orphan response view is emitted (0.8.0 renamed request-only DTOs to {Name}Input); types read and returned keep {Name} + {Name}Input (collision names {Name}Input2, ... unchanged). Fields read by a custom serde function (deserialize_with / with) are documented from their Rust type (or #[schema(value_type)]) in request views instead of an untyped {} — Option<Option<T>> is a nullable T — and a deserialize_with alone no longer creates a {Name}Input; with / serialize_with still document {} in responses. Response views follow what serde writes: Option<T> fields are required (nullable type; serde writes null) unless skip_serializing_if, and an Option skipped by skip_serializing_if = \"Option::is_none\" (serde_with #[skip_serializing_none]) is optional and not nullable since null is never written, and skip_serializing fields are absent instead of an optional writeOnly property; request views keep Option<T> optional, so a type with Option fields used on both sides gets a {Name}Input.","date":"2026-11-17T00:00:00.000Z"}
8 changes: 5 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -222,7 +222,9 @@ one-sided `skip_deserializing` / `skip_serializing`, or
`rename(deserialize = "..")` — request bodies reference a separate
`{Name}Input` component (defaulted fields optional, `skip_deserializing`
fields absent, deserialize names), FastAPI-style, while responses keep
`{Name}`. Types whose two views are identical get no extra component.
`{Name}`. Types whose two views are identical get no extra component, and a
type that is only read (no response reaches it) keeps its own name: `{Name}`
is then its request view and no `{Name}Input` is emitted.
`#[schema(name = "X")]` yields `XInput`; if that name is already taken the
first free `XInput2`, `XInput3`, … is used.

Expand Down Expand Up @@ -250,7 +252,7 @@ pub struct Rgb { pub r: u8, pub g: u8, pub b: u8 }
| Attribute | Documented as |
|---|---|
| field `#[schema(value_type = T)]` | `T`'s schema (constraints such as `minimum` still apply) |
| field `#[serde(with / serialize_with / deserialize_with)]` without `value_type` | `{}` (any value) with a description saying the shape is unknown — never the Rust type. One-sided `serialize_with` / `deserialize_with` only affects that direction (`{Name}Input` for requests); an `Option` read by a custom deserializer is `required` in requests, as in serde |
| field `#[serde(with / serialize_with / deserialize_with)]` without `value_type` | responses (`with` / `serialize_with`): `{}` (any value) with a description saying the shape is unknown; requests: the field's Rust type, like any other field (add `value_type` when the function reads another shape). An `Option` read by a custom deserializer is `required` in requests, as in serde |
| container `#[serde(into = "T")]` | responses use `T`; requests keep the fields (`{Name}Input`) |
| container `#[serde(from = "T")]` / `try_from` | requests use `T` (`{Name}Input`); responses keep the fields |
| container `#[schema(value_type = T)]` | `T` in both directions (wins over `into` / `from`) |
Expand Down Expand Up @@ -930,7 +932,7 @@ Fields with database defaults automatically get `default` values in the generate
| `default_value = "gen_random_uuid()"` | `"00000000-0000-0000-0000-000000000000"` |
| `default_value = "true"` | `true` (literal passthrough) |

> **Note:** `required` is determined solely by nullability (`Option<T>`). Fields with defaults are still `required` unless they are `Option<T>`.
> **Note:** In responses every field serde writes is `required` — defaulted fields, and `Option<T>` too (written as `null`, its type is nullable); only `skip_serializing_if` fields are optional — with `Option::is_none` (or serde_with's `#[skip_serializing_none]`) also not nullable, since `null` is never written — and `skip_serializing` fields are absent. In request bodies (`{Name}Input`, or `{Name}` for a request-only type) `#[serde(default)]` and `Option<T>` fields are optional.

### SeaORM Integration

Expand Down
8 changes: 4 additions & 4 deletions SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -240,7 +240,7 @@ pub async fn reindex() {}
| `bool` | `boolean` | |
| `Vec<T>` | `array` + items | |
| `BTreeSet<T>`, `HashSet<T>` | `array` + items + `uniqueItems: true` | Set types |
| `Option<T>` | T (nullable context) | Parent marks as optional |
| `Option<T>` | T, nullable | Required in responses (serde writes `null`), optional in request bodies |
| `HashMap<K,V>` | `object` + additionalProperties | |
| `Uuid` | `string` + `format: uuid` | |
| `Decimal` | `string` + `format: decimal` | |
Expand All @@ -253,7 +253,7 @@ pub async fn reindex() {}
| `url::Url` | `string` + `format: uri` | |
| `serde_json::Value`, SeaORM `Json` / `JsonValue` | `{}` | Any JSON value (a `Json<T>` with a type argument is axum's wrapper) |
| field `#[schema(value_type = T)]` | `T`'s schema | Use with `#[serde(with = ..)]` etc. |
| field `#[serde(with / serialize_with / deserialize_with)]` without `value_type` | `{}` + description note | Shape unknown; per direction for one-sided keys |
| field `#[serde(with / serialize_with / deserialize_with)]` without `value_type` | responses: `{}` + description note; requests: the Rust type | Response shape unknown (`with` / `serialize_with`); request views document the field's type |
| container `#[serde(into = "T")]` / `from` / `try_from` | `T` for responses / requests | Other direction keeps the fields (`{Name}Input`); container `#[schema(value_type = T)]` = both |
| `std::time::Duration` | `object` `{secs, nanos}` | serde's std shape; other qualified `Duration`s → `{}` |
| `()` | empty response | `200` without `content` (use `status = 204` for No Content) |
Expand Down Expand Up @@ -644,9 +644,9 @@ vespera::schema_type!(Schema from Model, name = "MemoSchema");

**Database Defaults in OpenAPI:** Fields with `#[sea_orm(default_value = "...")]` or `#[sea_orm(primary_key)]` automatically get `default` values in the generated OpenAPI schema. SQL functions like `NOW()` and `gen_random_uuid()` are mapped to type-appropriate defaults.

**Required Logic:** `required` follows nullability (`Option<T>`) and what serde writes: `skip_serializing` / `skip_serializing_if` fields are not required in the response view.
**Required Logic:** the response view requires every field serde writes (`Option<T>` included — it is written as `null`, with a nullable type); `skip_serializing_if` fields are not required (with `Option::is_none` / `#[skip_serializing_none]` the type is also not nullable — `null` is never written) and `skip_serializing` fields are absent. Request views make `Option<T>` and `#[serde(default)]` fields optional.

**Request views (`{Name}Input`):** when serde reads a type differently than it writes it (`#[serde(default)]` on a field or the container, one-sided `skip_deserializing` / `skip_serializing`, `rename(deserialize = ..)` / `rename_all(deserialize = ..)` differing from the serialize side, a container `into` / `from` / `try_from` documented through a different type per direction, a one-sided `serialize_with` / `deserialize_with`, an `Option` read by a custom deserializer (required in requests), or a field type that itself has an input view), request bodies (`Json` / `Form` / `TypedMultipart`) reference an extra `{Name}Input` component: defaulted fields are optional, `skip_deserializing` fields are absent, keys use the deserialize name. `{Name}` stays the response view. Nothing extra is emitted when both views are identical or no request body uses the type. `#[schema(name = "X")]` gives `XInput`; if that name is taken, `XInput2`, `XInput3`, ….
**Request views (`{Name}Input`):** when serde reads a type differently than it writes it (`#[serde(default)]` on a field or the container, one-sided `skip_deserializing` / `skip_serializing`, `rename(deserialize = ..)` / `rename_all(deserialize = ..)` differing from the serialize side, a container `into` / `from` / `try_from` documented through a different type per direction, a `with` / `serialize_with` (response shape unknown, request typed), an `Option` read by a custom deserializer (required in requests), or a field type that itself has an input view), request bodies (`Json` / `Form` / `TypedMultipart`) reference an extra `{Name}Input` component: defaulted fields are optional, `skip_deserializing` fields are absent, keys use the deserialize name. `{Name}` stays the response view. Nothing extra is emitted when both views are identical or no request body uses the type; a type only request bodies reach (no response, directly or transitively) keeps its name — `{Name}` is then its request view, no `{Name}Input`. `#[schema(name = "X")]` gives `XInput`; if that name is taken, `XInput2`, `XInput3`, ….

### Same-File Relation Adapters

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ pub struct Rgb { pub r: u8, pub g: u8, pub b: u8 }
</TableRow>
<TableRow>
<TableCell>Field `#[serde(with / serialize_with / deserialize_with)]` without `value_type`</TableCell>
<TableCell>`{}` (any value) with a description. A one-sided key only affects its direction</TableCell>
<TableCell>Responses (`with` / `serialize_with`): `{}` (any value) with a description. Requests: the field's Rust type, like any other field (add `value_type` when the custom function reads another shape)</TableCell>
</TableRow>
<TableRow>
<TableCell>Container `#[serde(into = "T")]`</TableCell>
Expand All @@ -99,7 +99,7 @@ An `Option` field read by a custom deserializer is `required` in request bodies,

## Request Views (`{Name}Input`)

serde can read a type differently than it writes it. When that happens, `Json` / `Form` / `TypedMultipart` request bodies reference an extra `{Name}Input` component, FastAPI-style, while responses keep using `{Name}`:
serde can read a type differently than it writes it. When that happens and the type is both read and returned, `Json` / `Form` / `TypedMultipart` request bodies reference an extra `{Name}Input` component, FastAPI-style, while responses keep using `{Name}`:

```rust
#[derive(Serialize, Deserialize, vespera::Schema)]
Expand All @@ -114,7 +114,7 @@ pub struct Settings {

A type gets an input view when it has `#[serde(default)]` on a field or the container, one-sided `skip_deserializing` / `skip_serializing`, a `rename(deserialize = "..")` / `rename_all(deserialize = "..")` that differs from the serialize side, a container `from` / `try_from`, or a field whose type has its own input view. In `{Name}Input` defaulted fields are not `required`, `skip_deserializing` fields are absent and keys use the deserialize names.

No `Input` component is emitted when both views are identical or no request body uses the type. `#[schema(name = "X")]` gives `XInput`; when a type already owns that name, the first free `XInput2`, `XInput3`, … is used. Types generated by `schema_type!` derive `Schema` too, so they follow the same rule.
No `Input` component is emitted when both views are identical or no request body uses the type. A type that is only read — used by request bodies (directly or through another request-only type) but reached by no response — keeps its own name: `{Name}` is its request view and no `{Name}Input` is emitted. In `CreateOrder { items: Vec<LineItem> }` used only as a request body, both `CreateOrder` and `LineItem` are request views; once a response also returns `LineItem`, it gets `LineItem` + `LineItemInput` and `CreateOrder.items` references `LineItemInput`. `#[schema(name = "X")]` gives `XInput`; when a type already owns that name, the first free `XInput2`, `XInput3`, … is used. Types generated by `schema_type!` derive `Schema` too, so they follow the same rule.

## Type Mapping

Expand Down Expand Up @@ -283,7 +283,7 @@ Fields with SeaORM database defaults get `default` values in the generated schem
| `default_value = "gen_random_uuid()"` | `"00000000-0000-0000-0000-000000000000"` |
| `default_value = "true"` | `true` |

> `required` is determined solely by nullability (`Option<T>`). Fields with defaults are still `required` unless they are `Option<T>`.
> In responses every field serde writes is `required` — defaulted fields, and `Option<T>` too (written as `null`, its type is nullable); only `skip_serializing_if` fields are optional — with `Option::is_none` (or serde_with's `#[skip_serializing_none]`) also not nullable, since `null` is never written — and `skip_serializing` fields are absent. In request bodies (`{Name}Input`, or `{Name}` for a request-only type) `#[serde(default)]` and `Option<T>` fields are optional.

## Configuring the OpenAPI Output

Expand Down
4 changes: 4 additions & 0 deletions apps/landing/src/app/documentation/[...name]/migration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,10 @@ These change the generated document without any code change:
- **`Form<T>` on `GET` / `HEAD`** is documented as query parameters (axum reads the query string there), not as a request body.
- **`TypedHeader<T>`** header names come from `T` — the wire name for known `headers::*` types, otherwise `T` in kebab-case (`XRequestId` → `x-request-id`) — instead of the argument binding; `TypedHeader(_)` is no longer dropped.
- **`#[serde(default)]` fields stay `required` in response schemas**; only the `{Name}Input` request view makes them optional.
- **Request-only types keep their name (0.8.1).** A type whose request view differs but that no response returns (directly or through another type) is emitted once, as its request view, under `{Name}` — 0.8.0 emitted an unused `{Name}` plus `{Name}Input`. Clients generated from 0.8.0 that use `PortfolioUpdateRequestInput`-style names go back to `PortfolioUpdateRequest`. Types used on both sides keep `{Name}` + `{Name}Input`.
- **`Option<T>` fields are `required` in responses (0.8.1)**: serde always writes them (`null` for `None`), so the response view requires them with a nullable type (`bio: string | null` instead of `bio?: string | null` in generated clients); a `skip_serializing_if` field stays optional, and with `skip_serializing_if = "Option::is_none"` (serde_with's `#[skip_serializing_none]` too) its type is no longer nullable (`email?: string`) — serde never writes `null` for it. Request views keep `Option<T>` optional, so a type with `Option` fields used in both requests and responses now gets a `{Name}Input`.
- **`skip_serializing` fields are absent from responses (0.8.1)** instead of an optional `writeOnly` property — serde never writes them; request views keep them.
- **`deserialize_with` / `with` fields are typed in request views (0.8.1)**: documented from the Rust type (or `#[schema(value_type = T)]`) instead of an untyped `{}`; `Option<Option<T>>` is a nullable `T`. A `deserialize_with` alone no longer creates a `{Name}Input`; `with` / `serialize_with` still document `{}` in responses.
- **Type mappings:** naive date-times / times (`NaiveDateTime`, `PrimitiveDateTime`, sea-orm `DateTime`, `NaiveTime`, `time::Time`) no longer carry the offset-requiring `date-time` / `time` format; unit structs are `{type: null}`; `Option<()>` is a single `null` type; `u8`–`u64` get `minimum: 0` (and `u8` / `u16` / `u32` a `maximum`); unknown types and unresolved generic parameters are `{}` (any) instead of `{type: object}`; user `Schema` types named like builtins (`Date`, `Decimal`, `Uuid`, …) keep their `$ref`.
- **Enums:** concrete generic enums (`ApiResponse<Vec<User>>`) are inlined with their type arguments; `serde_repr` enums are `{type: integer, enum: [...]}`; enum `{Name}Input` views follow the deserialize side; an internally tagged newtype variant over a closed or map payload merges the tag into the payload object.
- **`cfg`-gated route modules and handlers** that `#[route]` never registered are mounted under the same `#[cfg]` instead of being dropped (they stay out of the document); a bare handler argument named like a path segment no longer adds a duplicate path parameter.
Expand Down
4 changes: 3 additions & 1 deletion crates/vespera/tests/schema_round5.rs
Original file line number Diff line number Diff line change
Expand Up @@ -73,8 +73,10 @@ fn derived_schemas_compile_and_document_their_fields() {
};
assert_eq!((tree.value, tree.children.len()), (6, 0));

// `schema!` is the response view: serde never writes the
// `skip_serializing` `item` (the request view documents it).
let schema = vespera::schema!(WithSkipped);
let properties = schema.properties.expect("properties");
let keys: Vec<&str> = properties.keys().map(String::as_str).collect();
assert_eq!(keys, ["id", "item"]);
assert_eq!(keys, ["id"]);
}
5 changes: 4 additions & 1 deletion crates/vespera_macro/src/openapi_generator.rs
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@ mod route_claims;
mod tests_accuracy;
#[cfg(test)]
mod tests_parser_views;
#[cfg(test)]
mod tests_request_only;

use component_schemas::{
build_file_cache, build_schema_lookups, build_struct_file_index, parse_component_schemas,
Expand Down Expand Up @@ -145,7 +147,7 @@ pub fn try_generate_openapi_doc_with_metadata(
}
};
stage("component schemas");
let (paths, all_tags) = build_path_items(
let (mut paths, all_tags) = build_path_items(
metadata,
&known_schema_names,
&struct_definitions,
Expand All @@ -158,6 +160,7 @@ pub fn try_generate_openapi_doc_with_metadata(
crate::parser::schema::request_view::install(std::sync::Arc::default());
install_stored_defaults(std::sync::Arc::default());
component_schemas::prune_unreferenced_inputs(&mut schemas, &paths, &input_names);
component_schemas::collapse_request_only_inputs(&mut schemas, &mut paths, &input_names)?;
component_schemas::reject_internally_tagged_in_document(&schemas, &paths)?;
let security_config = security_config.unwrap_or_default();
let tags = build_tags(all_tags, security_config.tag_descriptions.as_ref());
Expand Down
Loading
Loading