Skip to main content

roas_overlay/
lib.rs

1//! OpenAPI Overlay Specification — parser, validator, and applier.
2//!
3//! Implements the [OpenAPI Overlay Specification](https://spec.openapis.org/overlay/v1.0.0.html):
4//! a sidecar document format that transforms OpenAPI documents through
5//! an ordered list of [JSONPath](https://www.rfc-editor.org/rfc/rfc9535)
6//! actions (`update`, `remove`, and v1.1's `copy`).
7//!
8//! ## Modules
9//!
10//! - [`common`] — version-agnostic helpers: `x-` extensions serde
11//!   helpers, RFC 9535 JSONPath wrapper, the
12//!   [§4.4.3.1](https://spec.openapis.org/overlay/v1.0.0.html#merging-rules)
13//!   recursive merge.
14//! - [`validation`] — [`Validate`](validation::Validate) trait,
15//!   [`ValidationOptions`](validation::ValidationOptions) flag set,
16//!   `Context` / `ValidationError` types.
17//! - [`apply`] — [`Apply`](apply::Apply) trait, [`ApplyOptions`](apply::ApplyOptions),
18//!   [`ApplyReport`](apply::ApplyReport), [`ApplyError`](apply::ApplyError).
19//! - [`v1_0`] — Overlay v1.0 document model + `Validate` / `Apply` impls.
20//!
21//! ## Applying an overlay
22//!
23//! ```no_run
24//! use enumset::EnumSet;
25//! use roas_overlay::apply::Apply;
26//! use roas_overlay::v1_0::Overlay;
27//!
28//! // Parse the overlay document (JSON or YAML).
29//! let overlay: Overlay = serde_json::from_str(r#"{
30//!     "overlay": "1.0.0",
31//!     "info": { "title": "Example", "version": "1.0.0" },
32//!     "actions": [
33//!         { "target": "$.info", "update": { "description": "Patched." } }
34//!     ]
35//! }"#).unwrap();
36//!
37//! // Parse the target OpenAPI document as untyped JSON.
38//! let mut target: serde_json::Value = serde_json::from_str(r#"{
39//!     "openapi": "3.1.0",
40//!     "info": { "title": "API", "version": "1.0.0" },
41//!     "paths": {}
42//! }"#).unwrap();
43//!
44//! // Apply the overlay in-place.
45//! let report = overlay.apply(&mut target, EnumSet::empty()).unwrap();
46//! assert_eq!(report.actions.len(), 1);
47//! assert_eq!(target["info"]["description"], "Patched.");
48//! ```
49
50pub mod apply;
51pub mod common;
52pub mod validation;
53
54#[cfg(feature = "v1_0")]
55pub mod v1_0;
56
57#[cfg(feature = "v1_1")]
58pub mod v1_1;