Stabilize OpenAPI Generation and Docs #79
Conversation
- **Determinism**: Enforced deterministic route registration order by switching internal `HashMap` to `BTreeMap`.
- **Schema Stability**:
- Updated `RustApiSchema` trait to include a `name()` method for unique component identification.
- Updated `derive(Schema)` macro to generate unique names for generic types (e.g., `Wrapper_String` instead of `Wrapper`), preventing collisions.
- Added panic-on-collision logic in `OpenApiSpec::register_in_place` to catch schema conflicts at build/runtime.
- **Reliability**:
- Added error handling to `/docs` endpoints to prevent panics during JSON serialization errors.
- Implemented `$ref` integrity validation (`OpenApiSpec::validate_integrity`) to ensure all schema references point to existing components.
- **Testing**:
- Added a regression snapshot test (`crates/rustapi-core/tests/snapshot_test.rs`) to guarantee stable and deterministic OpenAPI output.
- Verified generic schema collision handling and ref integrity with unit tests.
Co-authored-by: Tuntii <121901995+Tuntii@users.noreply.github.com>
|
👋 Jules, reporting for duty! I'm here to lend a hand with this pull request. When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down. I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job! For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with New to Jules? Learn more at jules.google/docs. For security, I will only act on instructions from the user who triggered this task. |
- **Lint Fixes**: Renamed unused `name` parameters to `_name` in `crates/rustapi-macros/src/derive_schema.rs` to satisfy clippy.
- **Snapshot Test Fix**: Updated `crates/rustapi-core/tests/snapshot_test.rs` to match the actual generated OpenAPI spec.
- Corrected `required` fields order for `FieldErrorSchema` (struct field order: `field`, `code`, `message`).
- Corrected `ErrorBodySchema` expectations (it has `Option` fields, so they are not `required`).
- Verified `fields` type in `ValidationErrorBodySchema` is `"array"` (Vec) vs `["array", "null"]` (Option<Vec>) in `ErrorBodySchema`.
- Added structural equality assertion for better error messages.
Co-authored-by: Tuntii <121901995+Tuntii@users.noreply.github.com>
- Collapsed nested `if` statement in `crates/rustapi-openapi/src/spec.rs` to satisfy `clippy::collapsible_if`. Co-authored-by: Tuntii <121901995+Tuntii@users.noreply.github.com>
This PR stabilizes the OpenAPI generation pipeline and
/docsendpoint behavior.Key Changes:
HashMapwithBTreeMapinRustApi::mount_auto_routes_groupedto ensure routes are registered in a consistent order across builds and runs.RustApiSchematrait with aname()method.#[derive(Schema)]to generate composite names for generic types (e.g.,Wrapper<T>->Wrapper_T), resolving schema collisions where multiple instantiations of a generic type would previously overwrite each other.OpenApiSpecnow detects and panics if two different schemas register with the same component name.validate_integrity()toOpenApiSpecto check that all$refpointers resolve to valid components./docsendpoint now handles JSON serialization errors gracefully instead of unwrapping.These changes ensure that RustAPI produces spec-compliant, deterministic, and stable OpenAPI documentation suitable for automated client generation and contract testing.
PR created automatically by Jules for task 16972392054356650202 started by @Tuntii