From 576a5b43ac56523890acca1df0e2fb905f53eccd Mon Sep 17 00:00:00 2001 From: includeamin Date: Sun, 22 Nov 2026 00:49:08 +0100 Subject: [PATCH 1/7] feat(core): add filter configuration --- README.md | 2 + crates/openapi-aggregator-core/src/config.rs | 178 +++++++++++++++++- crates/openapi-aggregator-core/src/lib.rs | 4 +- crates/openapi-aggregator-core/src/prepare.rs | 4 + .../tests/integration_test.rs | 19 ++ 5 files changed, 203 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 71159e0..b38c428 100644 --- a/README.md +++ b/README.md @@ -202,6 +202,7 @@ async fn main() -> Result<(), Box> { name: Some("petstore".into()), path: "./specs/petstore.yaml".into(), additional_blocks: None, + filter: None, tag_prefix: None, }, Source::Http { @@ -211,6 +212,7 @@ async fn main() -> Result<(), Box> { .into_iter() .collect(), additional_blocks: None, + filter: None, tag_prefix: None, }, ], diff --git a/crates/openapi-aggregator-core/src/config.rs b/crates/openapi-aggregator-core/src/config.rs index 1d5e663..cae103e 100644 --- a/crates/openapi-aggregator-core/src/config.rs +++ b/crates/openapi-aggregator-core/src/config.rs @@ -17,8 +17,15 @@ pub struct Config { impl Config { /// Parse a YAML (or JSON) config document. pub fn from_yaml(text: &str) -> Result { - serde_yaml::from_str(text) - .map_err(|e| crate::error::Error::Config(format!("failed to parse config file: {e}"))) + let config: Self = serde_yaml::from_str(text).map_err(|e| { + crate::error::Error::Config(format!("failed to parse config file: {e}")) + })?; + if let Some(filter) = &config.merge.filter { + filter.validate("merge.filter").map_err(|e| { + crate::error::Error::Config(format!("failed to parse config file: {e}")) + })?; + } + Ok(config) } } @@ -43,6 +50,8 @@ pub enum Source { /// Additional blocks deep-merged into this source spec before merge. /// Can be used for vendor extensions or any custom OpenAPI blocks. additional_blocks: Option, + /// Operations to hide from (or keep of) this source, in addition to `merge.filter`. + filter: Option, }, File { name: Option, @@ -53,6 +62,8 @@ pub enum Source { /// Additional blocks deep-merged into this source spec before merge. /// Can be used for vendor extensions or any custom OpenAPI blocks. additional_blocks: Option, + /// Operations to hide from (or keep of) this source, in addition to `merge.filter`. + filter: Option, }, } @@ -67,6 +78,7 @@ struct RawSource { headers: Option>, tag_prefix: Option, additional_blocks: Option, + filter: Option, } impl TryFrom for Source { @@ -78,6 +90,9 @@ impl TryFrom for Source { .as_deref() .map(|n| format!("source '{n}'")) .unwrap_or_else(|| "source".into()); + if let Some(filter) = &raw.filter { + filter.validate(&format!("{label} filter"))?; + } match (raw.url, raw.path) { (Some(url), None) => Ok(Source::Http { name: raw.name, @@ -85,6 +100,7 @@ impl TryFrom for Source { headers: raw.headers.unwrap_or_default(), tag_prefix: raw.tag_prefix, additional_blocks: raw.additional_blocks, + filter: raw.filter, }), (None, Some(path)) => { if raw.headers.is_some() { @@ -97,6 +113,7 @@ impl TryFrom for Source { path, tag_prefix: raw.tag_prefix, additional_blocks: raw.additional_blocks, + filter: raw.filter, }) } (Some(_), Some(_)) => Err(format!( @@ -136,6 +153,13 @@ impl Source { } } + /// The per-source operation filter, if any. + pub fn filter(&self) -> Option<&FilterConfig> { + match self { + Source::Http { filter, .. } | Source::File { filter, .. } => filter.as_ref(), + } + } + /// Return the tag prefix for this source: custom `tag_prefix` field if set, otherwise the display name. pub fn tag_prefix(&self) -> String { match self { @@ -146,6 +170,81 @@ impl Source { } } +/// Which operations a filter rule applies to. An operation matches when **any** criterion +/// matches. See [`FilterConfig`]. +#[derive(Debug, Clone, Default, Deserialize, Serialize, PartialEq, Eq)] +#[serde(deny_unknown_fields)] +pub struct FilterRules { + /// Path globs (`*` within one segment, `**` across segments), e.g. `/internal/**`. + #[serde(default)] + pub paths: Vec, + /// Operations having any of these tags. + #[serde(default)] + pub tags: Vec, + /// Operations with any of these `operationId`s. + #[serde(default)] + pub operation_ids: Vec, + /// Vendor extensions (`x-...`) that are truthy on the operation or its path item. + #[serde(default)] + pub extensions: Vec, +} + +impl FilterRules { + fn validate(&self, context: &str) -> Result<(), String> { + if self.paths.is_empty() + && self.tags.is_empty() + && self.operation_ids.is_empty() + && self.extensions.is_empty() + { + return Err(format!( + "{context} must list at least one rule (paths, tags, operation_ids or extensions)" + )); + } + for path in &self.paths { + if !path.starts_with('/') { + return Err(format!( + "{context}.paths entry '{path}' must start with '/'" + )); + } + } + for extension in &self.extensions { + if !extension.starts_with("x-") { + return Err(format!( + "{context}.extensions entry '{extension}' must start with 'x-'" + )); + } + } + for (key, entries) in [("tags", &self.tags), ("operation_ids", &self.operation_ids)] { + if entries.iter().any(|e| e.is_empty()) { + return Err(format!("{context}.{key} entries must not be empty")); + } + } + Ok(()) + } +} + +/// Select which operations end up in the merged spec: `exclude` hides matching operations, +/// `include` (an allow-list) keeps only matching ones. Exclude wins. +#[derive(Debug, Clone, Default, Deserialize, Serialize, PartialEq, Eq)] +#[serde(deny_unknown_fields)] +pub struct FilterConfig { + pub include: Option, + pub exclude: Option, +} + +impl FilterConfig { + /// Check the rules are well-formed; `context` names the config location for errors. + pub fn validate(&self, context: &str) -> Result<(), String> { + if let Some(rules) = &self.include { + rules.validate(&format!("{context}.include"))?; + } + if let Some(rules) = &self.exclude { + rules.validate(&format!("{context}.exclude"))?; + } + Ok(()) + } +} + /// Output configuration. #[derive(Debug, Clone, Deserialize, Serialize)] #[serde(deny_unknown_fields)] @@ -198,6 +297,8 @@ pub struct MergeConfig { /// If set, replaces any tags collected from sources. /// (Operation-level tag references are NOT rewritten; these should match.) pub tags: Option>, + /// Operations to hide from (or keep of) every source. + pub filter: Option, } impl Default for MergeConfig { @@ -210,6 +311,7 @@ impl Default for MergeConfig { info: None, servers: None, tags: None, + filter: None, } } } @@ -334,7 +436,79 @@ mod tests { headers: HashMap::new(), tag_prefix: None, additional_blocks: None, + filter: None, }; assert_eq!(source.display_name(), "billing.example.com"); } + + const FILTER_YAML: &str = " +sources: + - name: billing + path: billing.yaml + filter: + include: + tags: [public] +merge: + filter: + exclude: + paths: ['/internal/**', '/admin/*'] + tags: [internal] + operation_ids: [debugDump] + extensions: [x-internal] +"; + + #[test] + fn parses_filters() { + let config = Config::from_yaml(FILTER_YAML).unwrap(); + let global = config.merge.filter.as_ref().unwrap(); + assert!(global.include.is_none()); + let exclude = global.exclude.as_ref().unwrap(); + assert_eq!(exclude.paths, vec!["/internal/**", "/admin/*"]); + assert_eq!(exclude.tags, vec!["internal"]); + assert_eq!(exclude.operation_ids, vec!["debugDump"]); + assert_eq!(exclude.extensions, vec!["x-internal"]); + + let source_filter = config.sources[0].filter().unwrap(); + assert_eq!(source_filter.include.as_ref().unwrap().tags, vec!["public"]); + assert!(source_filter.exclude.is_none()); + } + + #[test] + fn configs_without_filters_have_none() { + let config = Config::from_yaml("sources:\n - path: a.yaml\n").unwrap(); + assert!(config.merge.filter.is_none()); + assert!(config.sources[0].filter().is_none()); + let http = Config::from_yaml("sources:\n - url: https://a.test/x\n").unwrap(); + assert!(http.sources[0].filter().is_none()); + } + + #[test] + fn invalid_filters_are_config_errors() { + let global = + |rules: &str| format!("sources:\n - path: a.yaml\nmerge:\n filter:\n {rules}\n"); + let source = |rules: &str| { + format!("sources:\n - name: s\n path: a.yaml\n filter:\n {rules}\n") + }; + let cases = [ + (global("exclude: {tag: [x]}"), "tag"), + (global("include: {}"), "merge.filter.include"), + (global("exclude: {tags: []}"), "at least one rule"), + ( + global("exclude: {paths: ['internal/**']}"), + "must start with '/'", + ), + ( + global("exclude: {extensions: [internal]}"), + "must start with 'x-'", + ), + (global("exclude: {tags: ['']}"), "empty"), + (source("include: {}"), "source 's'"), + (source("exclude: {operation_ids: ['']}"), "empty"), + (source("exclude: {paths: ['x']}"), "must start with '/'"), + ]; + for (yaml, fragment) in cases { + let err = Config::from_yaml(&yaml).unwrap_err().to_string(); + assert!(err.contains(fragment), "expected '{fragment}' in: {err}"); + } + } } diff --git a/crates/openapi-aggregator-core/src/lib.rs b/crates/openapi-aggregator-core/src/lib.rs index 7576b61..7c071c3 100644 --- a/crates/openapi-aggregator-core/src/lib.rs +++ b/crates/openapi-aggregator-core/src/lib.rs @@ -48,8 +48,8 @@ pub use bundle::{ MAX_DOCUMENTS, }; pub use config::{ - Config, ConflictStrategy, InfoOverride, MergeConfig, OutputConfig, OutputFormat, ServerEntry, - Source, TagEntry, TagPrefixStrategy, + Config, ConflictStrategy, FilterConfig, FilterRules, InfoOverride, MergeConfig, OutputConfig, + OutputFormat, ServerEntry, Source, TagEntry, TagPrefixStrategy, }; pub use error::Error; pub use merge::{merge_specs, merge_specs_with_report, MergeReport}; diff --git a/crates/openapi-aggregator-core/src/prepare.rs b/crates/openapi-aggregator-core/src/prepare.rs index cbf7a3c..24bcd5d 100644 --- a/crates/openapi-aggregator-core/src/prepare.rs +++ b/crates/openapi-aggregator-core/src/prepare.rs @@ -172,6 +172,7 @@ mod tests { } } })), + filter: None, }; let base = r#"{ @@ -200,6 +201,7 @@ mod tests { path: PathBuf::from("ignored.yaml"), tag_prefix: None, additional_blocks: Some(json!({ "x-team": "core" })), + filter: None, }; let (name, spec) = prepare_source( r#"{"openapi":"3.0.3","info":{"title":"T","version":"1"},"paths":{}}"#, @@ -226,6 +228,7 @@ mod tests { path: PathBuf::from("ignored.yaml"), tag_prefix: None, additional_blocks: blocks, + filter: None, } } @@ -282,6 +285,7 @@ mod tests { path: PathBuf::from("ignored.yaml"), tag_prefix: None, additional_blocks: Some(json!([1, 2, 3])), + filter: None, }; let base = r#"{"openapi":"3.0.3","info":{"title":"T","version":"1"},"paths":{}}"#; diff --git a/crates/openapi-aggregator/tests/integration_test.rs b/crates/openapi-aggregator/tests/integration_test.rs index 1884ed3..12037bb 100644 --- a/crates/openapi-aggregator/tests/integration_test.rs +++ b/crates/openapi-aggregator/tests/integration_test.rs @@ -16,6 +16,7 @@ async fn load_yaml_file_source() { path: fixtures().join("petstore.yaml"), tag_prefix: None, additional_blocks: None, + filter: None, }; let (name, spec) = load_source(&source).await.unwrap(); assert_eq!(name, "petstore"); @@ -30,6 +31,7 @@ async fn load_json_file_source() { path: fixtures().join("conflict.json"), tag_prefix: None, additional_blocks: None, + filter: None, }; let (name, spec) = load_source(&source).await.unwrap(); assert_eq!(name, "conflict"); @@ -45,12 +47,14 @@ async fn aggregate_two_specs_from_config() { path: fixtures().join("petstore.yaml"), tag_prefix: None, additional_blocks: None, + filter: None, }, Source::File { name: Some("users".into()), path: fixtures().join("users.yaml"), tag_prefix: None, additional_blocks: None, + filter: None, }, ], output: Default::default(), @@ -96,12 +100,14 @@ async fn aggregate_applies_additional_blocks_per_source() { } } })), + filter: None, }, Source::File { name: Some("users".into()), path: fixtures().join("users.yaml"), tag_prefix: None, additional_blocks: None, + filter: None, }, ], output: Default::default(), @@ -125,12 +131,14 @@ async fn aggregate_conflict_errors_by_default() { path: fixtures().join("petstore.yaml"), tag_prefix: None, additional_blocks: None, + filter: None, }, Source::File { name: Some("conflict".into()), path: fixtures().join("conflict.json"), tag_prefix: None, additional_blocks: None, + filter: None, }, ], output: Default::default(), @@ -152,12 +160,14 @@ async fn aggregate_conflict_rename_rewrites_refs() { path: fixtures().join("petstore.yaml"), tag_prefix: None, additional_blocks: None, + filter: None, }, Source::File { name: Some("alt".into()), path: fixtures().join("conflict.json"), tag_prefix: None, additional_blocks: None, + filter: None, }, ], output: Default::default(), @@ -264,6 +274,7 @@ async fn http_source_with_headers() { .collect(), tag_prefix: None, additional_blocks: None, + filter: None, }; let (name, spec) = load_source(&source).await.unwrap(); @@ -296,6 +307,7 @@ async fn http_source_rejects_non_success_status() { headers: Default::default(), tag_prefix: None, additional_blocks: None, + filter: None, }; let error = load_source(&source).await.unwrap_err(); @@ -325,6 +337,7 @@ async fn http_source_expands_env_vars_in_headers() { .collect(), tag_prefix: None, additional_blocks: None, + filter: None, }; let (_, spec) = load_source(&source).await.unwrap(); @@ -348,12 +361,14 @@ async fn aggregate_with_report_returns_version_warnings() { path: fixtures().join("petstore.yaml"), tag_prefix: None, additional_blocks: None, + filter: None, }, Source::File { name: Some("new".into()), path: v31, tag_prefix: None, additional_blocks: None, + filter: None, }, ], output: Default::default(), @@ -431,6 +446,7 @@ async fn http_errors_do_not_leak_expanded_env_secrets() { headers: Default::default(), tag_prefix: None, additional_blocks: None, + filter: None, }; let err = load_source(&source).await.unwrap_err(); @@ -466,12 +482,14 @@ async fn swagger2_source_merges_with_openapi3_and_refs_resolve() { path: fixtures().join("petstore.yaml"), tag_prefix: None, additional_blocks: None, + filter: None, }, Source::File { name: Some("legacy".into()), path: fixtures().join("swagger2.yaml"), tag_prefix: None, additional_blocks: None, + filter: None, }, ], output: Default::default(), @@ -705,6 +723,7 @@ fn http_config(url: String, headers: &[(&str, &str)]) -> Config { .collect(), tag_prefix: None, additional_blocks: None, + filter: None, }], output: Default::default(), merge: MergeConfig::default(), From d21ef0aca115e57e5b53cdceef5d13d742d652a9 Mon Sep 17 00:00:00 2001 From: includeamin Date: Sun, 22 Nov 2026 00:49:44 +0100 Subject: [PATCH 2/7] feat(core): add glob and filter rule matching --- crates/openapi-aggregator-core/src/filter.rs | 262 +++++++++++++++++++ crates/openapi-aggregator-core/src/lib.rs | 1 + 2 files changed, 263 insertions(+) create mode 100644 crates/openapi-aggregator-core/src/filter.rs diff --git a/crates/openapi-aggregator-core/src/filter.rs b/crates/openapi-aggregator-core/src/filter.rs new file mode 100644 index 0000000..4d5f070 --- /dev/null +++ b/crates/openapi-aggregator-core/src/filter.rs @@ -0,0 +1,262 @@ +//! Hide operations (e.g. internal endpoints) from a source before it is merged, and prune +//! the components, security schemes and tags that only those operations used. + +use serde_json::Value; + +use crate::config::FilterRules; + +#[derive(Clone, Copy, PartialEq)] +enum Token { + Literal(char), + /// `*`: any run of characters except `/`. + Star, + /// `**`: any run of characters, including `/`. + DoubleStar, +} + +fn tokenize(pattern: &str) -> Vec { + let mut tokens = Vec::new(); + let mut chars = pattern.chars().peekable(); + while let Some(c) = chars.next() { + if c != '*' { + tokens.push(Token::Literal(c)); + continue; + } + let mut stars = 1; + while chars.next_if_eq(&'*').is_some() { + stars += 1; + } + tokens.push(if stars == 1 { + Token::Star + } else { + Token::DoubleStar + }); + } + tokens +} + +/// Match `text` against a path glob: `*` matches within one segment (never `/`), `**` matches +/// across segments, everything else is literal. +pub fn glob_match(pattern: &str, text: &str) -> bool { + let tokens = tokenize(pattern); + let text: Vec = text.chars().collect(); + // reachable[j]: the tokens consumed so far can match text[..j]. + let mut reachable = vec![false; text.len() + 1]; + reachable[0] = true; + for token in tokens { + let mut next = vec![false; text.len() + 1]; + match token { + Token::Literal(c) => { + for j in 0..text.len() { + next[j + 1] = reachable[j] && text[j] == c; + } + } + Token::Star | Token::DoubleStar => { + let mut open = false; + for j in 0..=text.len() { + if reachable[j] { + open = true; + } + next[j] = open; + // A single `*` cannot cross a `/`. + if token == Token::Star && j < text.len() && text[j] == '/' { + open = false; + } + } + } + } + reachable = next; + } + reachable[text.len()] +} + +fn truthy(value: Option<&Value>) -> bool { + match value { + None | Some(Value::Null) | Some(Value::Bool(false)) => false, + Some(Value::Number(n)) => n.as_f64().is_some_and(|f| f != 0.0), + Some(Value::String(s)) => !s.is_empty(), + Some(_) => true, + } +} + +#[allow(dead_code)] // used by `remove_operations` in the next step +/// Whether an operation matches any criterion of `rules`. `path` is `None` for webhooks, which +/// disables the `paths` criterion. +pub(crate) fn rules_match( + rules: &FilterRules, + path: Option<&str>, + path_item: &Value, + op: &Value, +) -> bool { + if let Some(path) = path { + if rules.paths.iter().any(|glob| glob_match(glob, path)) { + return true; + } + } + if let Some(Value::Array(tags)) = op.get("tags") { + if tags + .iter() + .filter_map(Value::as_str) + .any(|tag| rules.tags.iter().any(|t| t == tag)) + { + return true; + } + } + if let Some(id) = op.get("operationId").and_then(Value::as_str) { + if rules.operation_ids.iter().any(|i| i == id) { + return true; + } + } + rules + .extensions + .iter() + .any(|ext| truthy(op.get(ext)) || truthy(path_item.get(ext))) +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + + #[test] + fn globs() { + assert!(glob_match("/internal/**", "/internal/a")); + assert!(glob_match("/internal/**", "/internal/a/b/c")); + assert!(!glob_match("/internal/**", "/internal")); + assert!(glob_match("/admin/*", "/admin/x")); + assert!(!glob_match("/admin/*", "/admin/a/b")); + assert!(!glob_match("/admin/*", "/admin")); + assert!(glob_match("/users/{id}", "/users/{id}")); + assert!(!glob_match("/users/{id}", "/users/1")); + assert!(glob_match("/a*c", "/abc")); + assert!(!glob_match("/a*c", "/a/c")); + assert!(glob_match("/**/health", "/x/y/health")); + assert!(glob_match("/pets", "/pets")); + assert!(!glob_match("/pets", "/pets/1")); + assert!(glob_match("", "")); + assert!(!glob_match("", "/x")); + assert!(glob_match("/x/***", "/x/a/b")); + } + + fn rules(json: Value) -> FilterRules { + serde_json::from_value(json).unwrap() + } + + #[test] + fn matches_each_criterion() { + let item = json!({}); + let op = json!({"operationId": "debugDump", "tags": ["internal", "x"], "x-internal": true}); + assert!(rules_match( + &rules(json!({"paths": ["/internal/**"]})), + Some("/internal/a"), + &item, + &op + )); + assert!(!rules_match( + &rules(json!({"paths": ["/internal/**"]})), + Some("/pets"), + &item, + &op + )); + assert!(rules_match( + &rules(json!({"tags": ["internal"]})), + Some("/p"), + &item, + &op + )); + assert!(!rules_match( + &rules(json!({"tags": ["public"]})), + Some("/p"), + &item, + &op + )); + assert!(rules_match( + &rules(json!({"operation_ids": ["debugDump"]})), + Some("/p"), + &item, + &op + )); + assert!(!rules_match( + &rules(json!({"operation_ids": ["other"]})), + Some("/p"), + &item, + &op + )); + assert!(rules_match( + &rules(json!({"extensions": ["x-internal"]})), + Some("/p"), + &item, + &op + )); + } + + #[test] + fn any_criterion_is_enough_and_empty_rules_match_nothing() { + let op = json!({"tags": ["a"]}); + let both = rules(json!({"paths": ["/nope"], "tags": ["a"]})); + assert!(rules_match(&both, Some("/p"), &json!({}), &op)); + assert!(!rules_match( + &FilterRules::default(), + Some("/p"), + &json!({}), + &op + )); + } + + #[test] + fn extension_truthiness() { + let r = rules(json!({"extensions": ["x-internal"]})); + for truthy in [ + json!(true), + json!("yes"), + json!(1), + json!({"a": 1}), + json!([1]), + ] { + assert!( + rules_match( + &r, + Some("/p"), + &json!({}), + &json!({"x-internal": truthy.clone()}) + ), + "{truthy}" + ); + } + for falsy in [json!(false), json!(0), json!(""), json!(null)] { + assert!( + !rules_match( + &r, + Some("/p"), + &json!({}), + &json!({"x-internal": falsy.clone()}) + ), + "{falsy}" + ); + } + assert!(!rules_match(&r, Some("/p"), &json!({}), &json!({}))); + } + + #[test] + fn extension_on_the_path_item_matches() { + let r = rules(json!({"extensions": ["x-internal"]})); + assert!(rules_match( + &r, + Some("/p"), + &json!({"x-internal": true}), + &json!({}) + )); + assert!(!rules_match( + &r, + Some("/p"), + &json!({"x-internal": false}), + &json!({}) + )); + } + + #[test] + fn webhooks_ignore_path_globs() { + let r = rules(json!({"paths": ["/**"]})); + assert!(!rules_match(&r, None, &json!({}), &json!({}))); + } +} diff --git a/crates/openapi-aggregator-core/src/lib.rs b/crates/openapi-aggregator-core/src/lib.rs index 7c071c3..ab3e912 100644 --- a/crates/openapi-aggregator-core/src/lib.rs +++ b/crates/openapi-aggregator-core/src/lib.rs @@ -38,6 +38,7 @@ pub mod bundle; pub mod config; pub mod error; +pub mod filter; pub mod merge; pub mod prepare; pub mod swagger2; From 08dde09b14e528f0f46eeef4a844cab604cea7cf Mon Sep 17 00:00:00 2001 From: includeamin Date: Sun, 22 Nov 2026 00:51:23 +0100 Subject: [PATCH 3/7] feat(core): remove operations matched by filter rules --- crates/openapi-aggregator-core/src/filter.rs | 274 ++++++++++++++++++- 1 file changed, 273 insertions(+), 1 deletion(-) diff --git a/crates/openapi-aggregator-core/src/filter.rs b/crates/openapi-aggregator-core/src/filter.rs index 4d5f070..5054ac5 100644 --- a/crates/openapi-aggregator-core/src/filter.rs +++ b/crates/openapi-aggregator-core/src/filter.rs @@ -1,6 +1,9 @@ //! Hide operations (e.g. internal endpoints) from a source before it is merged, and prune //! the components, security schemes and tags that only those operations used. +// The internal pieces are wired into `filter_spec` by the next step. +#![allow(dead_code)] + use serde_json::Value; use crate::config::FilterRules; @@ -79,7 +82,6 @@ fn truthy(value: Option<&Value>) -> bool { } } -#[allow(dead_code)] // used by `remove_operations` in the next step /// Whether an operation matches any criterion of `rules`. `path` is `None` for webhooks, which /// disables the `paths` criterion. pub(crate) fn rules_match( @@ -113,6 +115,88 @@ pub(crate) fn rules_match( .any(|ext| truthy(op.get(ext)) || truthy(path_item.get(ext))) } +/// Remove every operation that is not kept by the rules; returns whether anything was removed. +/// +/// An operation is kept iff no `exclude` rule matches it and every `include` rule matches it. +/// Path items (and webhooks) left without operations are removed too. +pub(crate) fn remove_operations( + spec: &mut Value, + include: &[&FilterRules], + exclude: &[&FilterRules], +) -> bool { + let paths = filter_items(spec, "paths", true, include, exclude); + let webhooks = filter_items(spec, "webhooks", false, include, exclude); + paths | webhooks +} + +fn filter_items( + spec: &mut Value, + key: &str, + match_paths: bool, + include: &[&FilterRules], + exclude: &[&FilterRules], +) -> bool { + let Some(Value::Object(items)) = spec.get_mut(key) else { + return false; + }; + let mut removed = false; + let names: Vec = items.keys().cloned().collect(); + for name in names { + let path = match_paths.then_some(name.as_str()); + let (drop_methods, had_operations, path_excluded) = { + let item = &items[&name]; + let methods: Vec<&str> = crate::swagger2::METHODS + .iter() + .copied() + .filter(|m| item.get(*m).is_some_and(Value::is_object)) + .collect(); + let drop_methods: Vec<&str> = methods + .iter() + .copied() + .filter(|m| { + let op = &item[*m]; + exclude.iter().any(|r| rules_match(r, path, item, op)) + || !include.iter().all(|r| rules_match(r, path, item, op)) + }) + .collect(); + let path_excluded = path.is_some_and(|p| { + exclude + .iter() + .any(|r| r.paths.iter().any(|glob| glob_match(glob, p))) + }); + ( + drop_methods + .into_iter() + .map(String::from) + .collect::>(), + !methods.is_empty(), + path_excluded, + ) + }; + + let Some(Value::Object(item)) = items.get_mut(&name) else { + continue; + }; + for method in &drop_methods { + item.shift_remove(method); + removed = true; + } + let remaining = crate::swagger2::METHODS + .iter() + .any(|m| item.get(*m).is_some_and(Value::is_object)); + let drop_item = if had_operations { + !remaining && !item.contains_key("$ref") + } else { + path_excluded + }; + if drop_item { + items.shift_remove(&name); + removed = true; + } + } + removed +} + #[cfg(test)] mod tests { use super::*; @@ -259,4 +343,192 @@ mod tests { let r = rules(json!({"paths": ["/**"]})); assert!(!rules_match(&r, None, &json!({}), &json!({}))); } + + fn doc(paths: Value) -> Value { + json!({"openapi":"3.0.3","info":{"title":"T","version":"1"},"paths":paths}) + } + + fn ok() -> Value { + json!({"200":{"description":"ok"}}) + } + + fn run(spec: &mut Value, include: Vec, exclude: Vec) -> bool { + let include: Vec<&FilterRules> = include.iter().collect(); + let exclude: Vec<&FilterRules> = exclude.iter().collect(); + remove_operations(spec, &include, &exclude) + } + + #[test] + fn exclude_by_path_glob_removes_paths() { + let mut spec = doc(json!({ + "/pets":{"get":{"responses":ok()}}, + "/internal/a":{"get":{"responses":ok()}}, + "/internal/b/c":{"post":{"responses":ok()}} + })); + assert!(run( + &mut spec, + vec![], + vec![rules(json!({"paths":["/internal/**"]}))] + )); + assert_eq!( + spec["paths"] + .as_object() + .unwrap() + .keys() + .collect::>(), + vec!["/pets"] + ); + } + + #[test] + fn exclude_by_tag_keeps_other_operations_and_shared_parameters() { + let mut spec = doc(json!({ + "/p/{id}":{ + "parameters":[{"name":"id","in":"path","required":true}], + "get":{"responses":ok()}, + "delete":{"tags":["internal"],"responses":ok()}}, + "/q":{ + "parameters":[{"name":"x","in":"query"}], + "get":{"tags":["internal"],"responses":ok()}} + })); + assert!(run( + &mut spec, + vec![], + vec![rules(json!({"tags":["internal"]}))] + )); + assert!(spec["paths"]["/p/{id}"].get("delete").is_none()); + assert!(spec["paths"]["/p/{id}"].get("get").is_some()); + assert!(spec["paths"]["/p/{id}"].get("parameters").is_some()); + assert!(spec["paths"].get("/q").is_none()); + } + + #[test] + fn include_is_an_allow_list_and_exclude_wins() { + let paths = json!({ + "/a":{"get":{"tags":["public"],"responses":ok()}}, + "/b":{"get":{"tags":["public","beta"],"responses":ok()}}, + "/c":{"get":{"tags":["private"],"responses":ok()}} + }); + let mut spec = doc(paths.clone()); + run(&mut spec, vec![rules(json!({"tags":["public"]}))], vec![]); + assert_eq!( + spec["paths"] + .as_object() + .unwrap() + .keys() + .collect::>(), + vec!["/a", "/b"] + ); + + let mut spec = doc(paths.clone()); + run( + &mut spec, + vec![rules(json!({"tags":["public"]}))], + vec![rules(json!({"tags":["beta"]}))], + ); + assert_eq!( + spec["paths"] + .as_object() + .unwrap() + .keys() + .collect::>(), + vec!["/a"] + ); + + // two include rules (global + source) must both match + let mut spec = doc(paths); + run( + &mut spec, + vec![ + rules(json!({"tags":["public"]})), + rules(json!({"paths":["/b"]})), + ], + vec![], + ); + assert_eq!( + spec["paths"] + .as_object() + .unwrap() + .keys() + .collect::>(), + vec!["/b"] + ); + } + + #[test] + fn path_item_extension_hides_all_its_operations() { + let mut spec = doc(json!({ + "/a":{"x-internal":true,"get":{"responses":ok()},"post":{"responses":ok()}}, + "/b":{"x-internal":false,"get":{"responses":ok()}} + })); + run( + &mut spec, + vec![], + vec![rules(json!({"extensions":["x-internal"]}))], + ); + assert_eq!( + spec["paths"] + .as_object() + .unwrap() + .keys() + .collect::>(), + vec!["/b"] + ); + } + + #[test] + fn webhooks_follow_the_non_path_rules() { + let mut spec = json!({"openapi":"3.1.0","info":{"title":"T","version":"1"},"webhooks":{ + "hidden":{"post":{"tags":["internal"],"responses":ok()}}, + "shown":{"post":{"responses":ok()}}}}); + let r = rules(json!({"tags":["internal"],"paths":["/**"]})); + assert!(run(&mut spec, vec![], vec![r])); + assert_eq!( + spec["webhooks"] + .as_object() + .unwrap() + .keys() + .collect::>(), + vec!["shown"] + ); + } + + #[test] + fn nothing_matching_changes_nothing() { + let original = doc(json!({"/a":{"get":{"responses":ok()}},"/ref":{"$ref":"#/paths/~1a"}})); + let mut spec = original.clone(); + assert!(!run( + &mut spec, + vec![], + vec![rules(json!({"tags":["nope"]}))] + )); + assert_eq!(spec, original); + // a $ref-only path item is kept unless a path glob excludes it + let mut spec = original.clone(); + assert!(run( + &mut spec, + vec![], + vec![rules(json!({"paths":["/ref"]}))] + )); + assert!(spec["paths"].get("/ref").is_none() && spec["paths"].get("/a").is_some()); + } + + #[test] + fn surviving_paths_keep_their_order() { + let mut spec = doc(json!({ + "/hidden":{"get":{"tags":["internal"],"responses":ok()}}, + "/b":{"get":{"responses":ok()}}, + "/c":{"get":{"responses":ok()}}, + "/d":{"get":{"responses":ok()}} + })); + run(&mut spec, vec![], vec![rules(json!({"tags":["internal"]}))]); + assert_eq!( + spec["paths"] + .as_object() + .unwrap() + .keys() + .collect::>(), + vec!["/b", "/c", "/d"] + ); + } } From c0a3d195b2a48dae3abcf610507669e7b5120b6e Mon Sep 17 00:00:00 2001 From: includeamin Date: Sun, 22 Nov 2026 00:52:29 +0100 Subject: [PATCH 4/7] feat(core): prune components, schemes and tags orphaned by filtering --- crates/openapi-aggregator-core/src/filter.rs | 318 ++++++++++++++++++- crates/openapi-aggregator-core/src/lib.rs | 1 + 2 files changed, 317 insertions(+), 2 deletions(-) diff --git a/crates/openapi-aggregator-core/src/filter.rs b/crates/openapi-aggregator-core/src/filter.rs index 5054ac5..651afd1 100644 --- a/crates/openapi-aggregator-core/src/filter.rs +++ b/crates/openapi-aggregator-core/src/filter.rs @@ -1,8 +1,7 @@ //! Hide operations (e.g. internal endpoints) from a source before it is merged, and prune //! the components, security schemes and tags that only those operations used. -// The internal pieces are wired into `filter_spec` by the next step. -#![allow(dead_code)] +use std::collections::HashSet; use serde_json::Value; @@ -197,6 +196,187 @@ fn filter_items( removed } +/// What a spec uses: reachable components `(section, name)`, security scheme names and tag names. +#[derive(Default)] +struct Usage { + components: HashSet<(String, String)>, + schemes: HashSet, + tags: HashSet, +} + +/// `discriminator.mapping` targets are plain strings, not `$ref`s; collect them too. +fn mapping_targets(value: &Value, out: &mut Vec) { + match value { + Value::Object(map) => { + if let Some(Value::Object(mapping)) = + map.get("discriminator").and_then(|d| d.get("mapping")) + { + out.extend(mapping.values().filter_map(Value::as_str).map(String::from)); + } + map.values().for_each(|v| mapping_targets(v, out)); + } + Value::Array(items) => items.iter().for_each(|v| mapping_targets(v, out)), + _ => {} + } +} + +fn security_requirement_names(requirements: &Value, out: &mut HashSet) { + for requirement in requirements + .as_array() + .into_iter() + .flatten() + .filter_map(Value::as_object) + { + out.extend(requirement.keys().cloned()); + } +} + +/// Security requirement names: every `security: [{name: [...]}]` array outside `components`. +fn security_names(value: &Value, out: &mut HashSet) { + match value { + Value::Object(map) => { + for (key, child) in map { + match child { + Value::Array(reqs) + if key == "security" && reqs.iter().all(Value::is_object) => + { + for req in reqs.iter().filter_map(Value::as_object) { + out.extend(req.keys().cloned()); + } + } + _ => security_names(child, out), + } + } + } + Value::Array(items) => items.iter().for_each(|v| security_names(v, out)), + _ => {} + } +} + +fn component_of(reference: &str) -> Option<(String, String)> { + let segments = crate::bundle::decode_pointer(reference.strip_prefix('#')?); + match segments.as_slice() { + [c, section, name, ..] if c == "components" => Some((section.clone(), name.clone())), + _ => None, + } +} + +fn usage(spec: &Value) -> Usage { + let mut usage = Usage::default(); + let Some(root) = spec.as_object() else { + return usage; + }; + + let mut pending: Vec = Vec::new(); + for (key, value) in root.iter().filter(|(k, _)| *k != "components") { + crate::bundle::walk_refs(value, &mut |r| pending.push(r.to_string())); + mapping_targets(value, &mut pending); + if key == "security" { + security_requirement_names(value, &mut usage.schemes); + } else { + security_names(value, &mut usage.schemes); + } + if key == "paths" || key == "webhooks" { + for item in value.as_object().into_iter().flat_map(|m| m.values()) { + for method in crate::swagger2::METHODS { + let tags = item + .get(method) + .and_then(|op| op.get("tags")) + .and_then(Value::as_array); + usage.tags.extend( + tags.into_iter() + .flatten() + .filter_map(Value::as_str) + .map(String::from), + ); + } + } + } + } + + while let Some(reference) = pending.pop() { + let Some((section, name)) = component_of(&reference) else { + continue; + }; + if !usage.components.insert((section.clone(), name.clone())) { + continue; + } + if let Some(component) = spec.pointer(&format!( + "/components/{}/{}", + crate::validate::pointer_escape(§ion), + crate::validate::pointer_escape(&name) + )) { + crate::bundle::walk_refs(component, &mut |r| pending.push(r.to_string())); + mapping_targets(component, &mut pending); + } + } + usage +} + +/// Remove one component (and its section when that empties it); returns whether it existed. +fn remove_component(spec: &mut Value, section: &str, name: &str) -> bool { + let Some(Value::Object(components)) = spec.get_mut("components") else { + return false; + }; + let Some(Value::Object(entries)) = components.get_mut(section) else { + return false; + }; + let existed = entries.shift_remove(name).is_some(); + if existed && entries.is_empty() { + components.shift_remove(section); + } + existed +} + +fn prune(spec: &mut Value, before: &Usage, after: &Usage) { + let mut pruned = false; + for (section, name) in before.components.difference(&after.components) { + pruned |= remove_component(spec, section, name); + } + for name in before.schemes.difference(&after.schemes) { + pruned |= remove_component(spec, "securitySchemes", name); + } + // `components` is only dropped when pruning is what emptied it. + if pruned + && spec + .get("components") + .and_then(Value::as_object) + .is_some_and(|c| c.is_empty()) + { + if let Some(root) = spec.as_object_mut() { + root.shift_remove("components"); + } + } + if let Some(Value::Array(tags)) = spec.get_mut("tags") { + let had = !tags.is_empty(); + tags.retain(|tag| { + let name = tag.get("name").and_then(Value::as_str).unwrap_or(""); + !(before.tags.contains(name) && !after.tags.contains(name)) + }); + if had && tags.is_empty() { + if let Some(root) = spec.as_object_mut() { + root.shift_remove("tags"); + } + } + } +} + +/// Hide the operations the rules do not keep and prune what only they used: components, +/// security schemes and tags that were in use before but are not any more. Returns whether +/// anything was removed (when `false` the spec is untouched). +pub fn filter_spec(spec: &mut Value, include: &[&FilterRules], exclude: &[&FilterRules]) -> bool { + if include.is_empty() && exclude.is_empty() { + return false; + } + let before = usage(spec); + if !remove_operations(spec, include, exclude) { + return false; + } + let after = usage(spec); + prune(spec, &before, &after); + true +} + #[cfg(test)] mod tests { use super::*; @@ -531,4 +711,138 @@ mod tests { vec!["/b", "/c", "/d"] ); } + + fn api() -> Value { + json!({ + "openapi": "3.0.3", + "info": {"title": "T", "version": "1"}, + "tags": [{"name": "pub"}, {"name": "internal"}, {"name": "unusedTag"}], + "paths": { + "/public": {"get": {"tags": ["pub"], "security": [{"publicKey": []}], "responses": { + "200": {"description": "ok", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Pet"}}}}}}}, + "/internal": {"get": {"tags": ["internal"], "security": [{"internalKey": []}], + "parameters": [{"$ref": "#/components/parameters/InternalHeader"}], + "responses": { + "200": {"description": "ok", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Secret"}}}}, + "404": {"$ref": "#/components/responses/InternalNotFound"}}}} + }, + "components": { + "schemas": { + "Pet": {"type": "object", "properties": {"shared": {"$ref": "#/components/schemas/Shared"}}}, + "Shared": {"type": "string"}, + "Secret": {"type": "object", "properties": {"inner": {"$ref": "#/components/schemas/Inner"}, "pet": {"$ref": "#/components/schemas/Pet"}}}, + "Inner": {"type": "object", "properties": {"back": {"$ref": "#/components/schemas/Secret"}}}, + "Orphan": {"type": "string"} + }, + "parameters": {"InternalHeader": {"name": "X-Internal", "in": "header", "schema": {"type": "string"}}}, + "responses": {"InternalNotFound": {"description": "nf"}}, + "securitySchemes": { + "publicKey": {"type": "apiKey", "name": "k", "in": "header"}, + "internalKey": {"type": "apiKey", "name": "i", "in": "header"} + } + } + }) + } + + fn hide_internal(spec: &mut Value) -> bool { + let r = rules(json!({"tags": ["internal"]})); + filter_spec(spec, &[], &[&r]) + } + + fn names(spec: &Value, section: &str) -> Vec { + spec["components"][section] + .as_object() + .map(|m| m.keys().cloned().collect()) + .unwrap_or_default() + } + + #[test] + fn schemas_only_hidden_operations_used_are_pruned() { + let mut spec = api(); + assert!(hide_internal(&mut spec)); + // Secret <-> Inner (a cycle) was only reachable from the hidden operation. + assert_eq!(names(&spec, "schemas"), vec!["Pet", "Shared", "Orphan"]); + } + + #[test] + fn parameters_and_responses_are_pruned_and_emptied_sections_removed() { + let mut spec = api(); + hide_internal(&mut spec); + assert!(spec["components"].get("parameters").is_none()); + assert!(spec["components"].get("responses").is_none()); + assert!(spec["components"].get("schemas").is_some()); + } + + #[test] + fn pre_existing_empty_sections_are_left_alone() { + let mut spec = api(); + spec["components"]["examples"] = json!({}); + hide_internal(&mut spec); + assert_eq!(spec["components"]["examples"], json!({})); + } + + #[test] + fn components_is_removed_when_pruning_empties_it() { + let mut spec = json!({"openapi":"3.0.3","info":{"title":"T","version":"1"}, + "paths":{"/a":{"get":{"tags":["internal"],"responses":{"200":{"description":"ok","content":{ + "application/json":{"schema":{"$ref":"#/components/schemas/S"}}}}}}}}, + "components":{"schemas":{"S":{"type":"string"}}}}); + hide_internal(&mut spec); + assert!(spec.get("components").is_none()); + } + + #[test] + fn discriminator_mapping_targets_count_as_references() { + let mut spec = api(); + spec["components"]["schemas"]["Secret"]["discriminator"] = + json!({"propertyName": "k", "mapping": {"x": "#/components/schemas/SubSecret"}}); + spec["components"]["schemas"]["SubSecret"] = json!({"type": "object"}); + hide_internal(&mut spec); + assert!(!names(&spec, "schemas").contains(&"SubSecret".to_string())); + } + + #[test] + fn security_schemes_follow_their_users() { + let mut spec = api(); + hide_internal(&mut spec); + assert_eq!(names(&spec, "securitySchemes"), vec!["publicKey"]); + + let mut spec = api(); + spec["security"] = json!([{"internalKey": []}]); + hide_internal(&mut spec); + assert_eq!( + names(&spec, "securitySchemes"), + vec!["publicKey", "internalKey"] + ); + } + + #[test] + fn tags_used_only_by_hidden_operations_are_pruned() { + let mut spec = api(); + hide_internal(&mut spec); + let tags: Vec<&str> = spec["tags"] + .as_array() + .unwrap() + .iter() + .map(|t| t["name"].as_str().unwrap()) + .collect(); + assert_eq!(tags, vec!["pub", "unusedTag"]); + + let mut spec = json!({"openapi":"3.0.3","info":{"title":"T","version":"1"}, + "tags":[{"name":"internal"}], + "paths":{"/a":{"get":{"tags":["internal"],"responses":ok()}},"/b":{"get":{"responses":ok()}}}}); + hide_internal(&mut spec); + assert!(spec.get("tags").is_none()); + } + + #[test] + fn nothing_removed_means_nothing_pruned() { + let mut spec = api(); + let before = spec.clone(); + let r = rules(json!({"tags": ["nope"]})); + assert!(!filter_spec(&mut spec, &[], &[&r])); + assert_eq!(spec, before); + assert!(!filter_spec(&mut spec, &[], &[])); + assert_eq!(spec, before); + } } diff --git a/crates/openapi-aggregator-core/src/lib.rs b/crates/openapi-aggregator-core/src/lib.rs index ab3e912..b1a9d52 100644 --- a/crates/openapi-aggregator-core/src/lib.rs +++ b/crates/openapi-aggregator-core/src/lib.rs @@ -53,6 +53,7 @@ pub use config::{ OutputFormat, ServerEntry, Source, TagEntry, TagPrefixStrategy, }; pub use error::Error; +pub use filter::{filter_spec, glob_match}; pub use merge::{merge_specs, merge_specs_with_report, MergeReport}; pub use prepare::{ bundle_source, parse_content, prepare_source, prepare_source_with_notes, PreparedSource, From ac954271a1f1d019d7cc68c7848295995099cff1 Mon Sep 17 00:00:00 2001 From: includeamin Date: Sun, 22 Nov 2026 00:53:07 +0100 Subject: [PATCH 5/7] feat: apply operation filters before merging --- crates/openapi-aggregator-core/src/lib.rs | 3 +- crates/openapi-aggregator-core/src/prepare.rs | 71 +++++++++++++++- crates/openapi-aggregator-wasm/src/lib.rs | 18 ++++- crates/openapi-aggregator/src/lib.rs | 17 ++-- .../tests/integration_test.rs | 81 +++++++++++++++++++ 5 files changed, 180 insertions(+), 10 deletions(-) diff --git a/crates/openapi-aggregator-core/src/lib.rs b/crates/openapi-aggregator-core/src/lib.rs index b1a9d52..8dde525 100644 --- a/crates/openapi-aggregator-core/src/lib.rs +++ b/crates/openapi-aggregator-core/src/lib.rs @@ -56,6 +56,7 @@ pub use error::Error; pub use filter::{filter_spec, glob_match}; pub use merge::{merge_specs, merge_specs_with_report, MergeReport}; pub use prepare::{ - bundle_source, parse_content, prepare_source, prepare_source_with_notes, PreparedSource, + bundle_source, filter_source, parse_content, prepare_source, prepare_source_with_notes, + PreparedSource, }; pub use validate::{validate, Finding, Severity}; diff --git a/crates/openapi-aggregator-core/src/prepare.rs b/crates/openapi-aggregator-core/src/prepare.rs index 24bcd5d..b3d164d 100644 --- a/crates/openapi-aggregator-core/src/prepare.rs +++ b/crates/openapi-aggregator-core/src/prepare.rs @@ -3,8 +3,9 @@ use std::collections::HashMap; use serde_json::Value; use crate::bundle::bundle; -use crate::config::Source; +use crate::config::{FilterConfig, FilterRules, Source}; use crate::error::Error; +use crate::filter::filter_spec; use crate::merge::deep_merge; use crate::swagger2; @@ -56,6 +57,31 @@ pub fn bundle_source( Ok(prepared) } +/// Apply the global (`merge.filter`) and per-source filters to a prepared source, hiding the +/// operations they exclude and pruning what only those operations used. +/// +/// Every defined `exclude` applies; every defined `include` must match (the levels narrow). +/// With no filters this is a no-op. +pub fn filter_source( + mut prepared: PreparedSource, + global: Option<&FilterConfig>, + source: Option<&FilterConfig>, +) -> PreparedSource { + let levels = [global, source]; + let exclude: Vec<&FilterRules> = levels + .iter() + .flatten() + .filter_map(|f| f.exclude.as_ref()) + .collect(); + let include: Vec<&FilterRules> = levels + .iter() + .flatten() + .filter_map(|f| f.include.as_ref()) + .collect(); + filter_spec(&mut prepared.spec, &include, &exclude); + prepared +} + fn parse_and_prepare(content: &str, source: &Source) -> Result<(Value, Vec), Error> { let mut value = parse_content(content)?; let mut notes = Vec::new(); @@ -370,4 +396,47 @@ mod tests { .to_string(); assert!(err.contains("limit 100") && err.contains("x"), "{err}"); } + + fn filter_cfg(yaml: &str) -> FilterConfig { + serde_yaml::from_str(yaml).unwrap() + } + + fn two_op_source() -> PreparedSource { + let source = file_source("svc", None); + prepare_source_with_notes( + r#"{"openapi":"3.0.3","info":{"title":"T","version":"1"},"paths":{ + "/a":{"get":{"tags":["public"],"responses":{"200":{"description":"ok"}}}}, + "/b":{"get":{"tags":["public","beta"],"responses":{"200":{"description":"ok"}}}}, + "/c":{"get":{"tags":["private"],"responses":{"200":{"description":"ok"}}}}}}"#, + &source, + ) + .unwrap() + } + + fn path_names(prepared: &PreparedSource) -> Vec { + prepared.spec["paths"] + .as_object() + .unwrap() + .keys() + .cloned() + .collect() + } + + #[test] + fn filter_source_combines_global_and_source_rules() { + let global = filter_cfg("exclude: {tags: [beta]}"); + let local = filter_cfg("include: {tags: [public]}"); + let filtered = filter_source(two_op_source(), Some(&global), Some(&local)); + assert_eq!(path_names(&filtered), vec!["/a"]); + + let only_global = filter_source(two_op_source(), Some(&global), None); + assert_eq!(path_names(&only_global), vec!["/a", "/c"]); + } + + #[test] + fn filter_source_without_filters_changes_nothing() { + let before = two_op_source(); + let after = filter_source(two_op_source(), None, None); + assert_eq!(after.spec, before.spec); + } } diff --git a/crates/openapi-aggregator-wasm/src/lib.rs b/crates/openapi-aggregator-wasm/src/lib.rs index 736bc24..1cf0884 100644 --- a/crates/openapi-aggregator-wasm/src/lib.rs +++ b/crates/openapi-aggregator-wasm/src/lib.rs @@ -4,8 +4,9 @@ use std::collections::{BTreeMap, HashMap}; use openapi_aggregator_core::{ - bundle_source, check_document_cap, merge_specs_with_report, missing_documents, parse_content, - prepare_source_with_notes, validate, Config, Error, OutputFormat, PreparedSource, Source, + bundle_source, check_document_cap, filter_source, merge_specs_with_report, missing_documents, + parse_content, prepare_source_with_notes, validate, Config, Error, OutputFormat, + PreparedSource, Source, }; use serde::Serialize; use wasm_bindgen::prelude::*; @@ -185,6 +186,7 @@ pub fn aggregate_contents( check_document_cap(docs.len(), &prepared.name).map_err(|e| e.to_string())?; let prepared = bundle_source(prepared, &base_of(source), &docs).map_err(|e| e.to_string())?; + let prepared = filter_source(prepared, config.merge.filter.as_ref(), source.filter()); notes.extend(prepared.notes); specs.push((prepared.name, source.tag_prefix(), prepared.spec)); } @@ -470,4 +472,16 @@ mod tests { .unwrap(); assert!(clean.findings.is_empty(), "{:?}", clean.findings); } + + #[test] + fn filters_hide_operations_in_the_output() { + let spec = "openapi: 3.0.3\ninfo: {title: S, version: '1'}\npaths:\n /pub:\n get:\n responses: {'200': {description: ok}}\n /internal/x:\n get:\n responses: {'200': {description: ok}}\n"; + let config = "sources:\n - path: s.yaml\nmerge:\n filter:\n exclude:\n paths: ['/internal/**']\n"; + let out = aggregate_contents(config, vec![spec.into()], HashMap::new()).unwrap(); + assert!( + out.text.contains("/pub:") && !out.text.contains("/internal"), + "{}", + out.text + ); + } } diff --git a/crates/openapi-aggregator/src/lib.rs b/crates/openapi-aggregator/src/lib.rs index 3b894ef..472da6c 100644 --- a/crates/openapi-aggregator/src/lib.rs +++ b/crates/openapi-aggregator/src/lib.rs @@ -12,11 +12,11 @@ pub mod source; pub use error::Error; pub use openapi_aggregator_core::{ - bundle_source, check_document_cap, config, is_url, merge, merge_specs, merge_specs_with_report, - missing_documents, parse_content, prepare_source, prepare_source_with_notes, resolve_location, - validate, Config, ConflictStrategy, Finding, InfoOverride, MergeConfig, MergeReport, - MissingDocument, OutputConfig, OutputFormat, PreparedSource, ServerEntry, Severity, Source, - TagEntry, TagPrefixStrategy, + bundle_source, check_document_cap, config, filter_source, is_url, merge, merge_specs, + merge_specs_with_report, missing_documents, parse_content, prepare_source, + prepare_source_with_notes, resolve_location, validate, Config, ConflictStrategy, Finding, + InfoOverride, MergeConfig, MergeReport, MissingDocument, OutputConfig, OutputFormat, + PreparedSource, ServerEntry, Severity, Source, TagEntry, TagPrefixStrategy, }; pub use source::load_source; @@ -68,7 +68,12 @@ pub async fn aggregate_with_options( }; let prepared = try_join_all(config.sources.iter().map(|src| async { let prepared = load_source_with_client(src, &client).await?; - refs::resolve_external_refs(prepared, src, &ctx).await + let prepared = refs::resolve_external_refs(prepared, src, &ctx).await?; + Ok::<_, Error>(filter_source( + prepared, + config.merge.filter.as_ref(), + src.filter(), + )) })) .await?; diff --git a/crates/openapi-aggregator/tests/integration_test.rs b/crates/openapi-aggregator/tests/integration_test.rs index 12037bb..0eb5796 100644 --- a/crates/openapi-aggregator/tests/integration_test.rs +++ b/crates/openapi-aggregator/tests/integration_test.rs @@ -825,3 +825,84 @@ async fn url_source_cannot_read_local_files() { .to_string(); assert!(err.contains("file:"), "{err}"); } + +// --------------------------------------------------------------------------- +// operation filters +// --------------------------------------------------------------------------- + +fn service_spec(name: &str, public_path: &str) -> String { + format!( + "openapi: 3.0.3 +info: {{title: {name}, version: '1'}} +tags: [{{name: internal}}, {{name: public}}] +paths: + {public_path}: + get: + tags: [public] + responses: + '200': + description: ok + content: + application/json: + schema: {{$ref: '#/components/schemas/Shared'}} + /internal/metrics: + get: + tags: [internal] + responses: + '200': + description: ok + content: + application/json: + schema: {{$ref: '#/components/schemas/{name}Internal'}} +components: + schemas: + Shared: {{type: string}} + {name}Internal: {{type: object}} +" + ) +} + +fn filter_dir(config: &str) -> tempfile::TempDir { + let dir = tempfile::tempdir().unwrap(); + write(&dir.path().join("a.yaml"), &service_spec("A", "/a")); + write(&dir.path().join("b.yaml"), &service_spec("B", "/b")); + write(&dir.path().join("cfg.yaml"), config); + dir +} + +const TWO_SOURCES: &str = + "sources:\n - name: a\n path: a.yaml\n - name: b\n path: b.yaml\n"; + +#[tokio::test] +async fn excluded_operations_no_longer_conflict_and_are_pruned() { + let dir = filter_dir(&format!( + "{TWO_SOURCES}merge:\n filter:\n exclude:\n paths: ['/internal/**']\n" + )); + let report = run_config(dir.path(), false).await.unwrap(); + let paths: Vec<&String> = report.spec["paths"].as_object().unwrap().keys().collect(); + assert_eq!(paths, vec!["/a", "/b"]); + let schemas: Vec<&String> = report.spec["components"]["schemas"] + .as_object() + .unwrap() + .keys() + .collect(); + assert_eq!(schemas, vec!["Shared"]); + let tags = serde_json::to_string(&report.spec["tags"]).unwrap(); + assert!(!tags.contains("internal"), "{tags}"); +} + +#[tokio::test] +async fn without_a_filter_the_same_sources_still_conflict() { + let dir = filter_dir(TWO_SOURCES); + assert!(run_config(dir.path(), false).await.is_err()); +} + +#[tokio::test] +async fn source_level_include_narrows_only_that_source() { + let dir = filter_dir( + "sources:\n - name: a\n path: a.yaml\n filter:\n include:\n tags: [public]\n - name: b\n path: b.yaml\n filter:\n exclude:\n tags: [internal]\n", + ); + let report = run_config(dir.path(), false).await.unwrap(); + let paths: Vec<&String> = report.spec["paths"].as_object().unwrap().keys().collect(); + assert_eq!(paths, vec!["/a", "/b"]); +} From aaaf5005c7dd6a3ad3b4f143beff10595f4e43b7 Mon Sep 17 00:00:00 2001 From: includeamin Date: Sun, 22 Nov 2026 00:54:18 +0100 Subject: [PATCH 6/7] feat(web): add a "hide internal endpoints" example --- web/src/examples.ts | 130 +++++++++++++++++++++++++++++++++++++ web/tests/examples.test.ts | 16 +++++ 2 files changed, 146 insertions(+) diff --git a/web/src/examples.ts b/web/src/examples.ts index aa8cdd9..0642b0b 100644 --- a/web/src/examples.ts +++ b/web/src/examples.ts @@ -213,6 +213,108 @@ const MULTI_AUTHOR = `Author: name: { type: string } `; +const HIDE_BILLING = `openapi: 3.0.3 +info: + title: Billing API + version: 1.0.0 +tags: + - name: invoices + - name: internal +paths: + /invoices: + get: + tags: [invoices] + summary: List invoices + responses: + '200': + description: Invoices + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Invoice' + /internal/metrics: + get: + tags: [internal] + summary: Billing metrics + responses: + '200': + description: Metrics + content: + application/json: + schema: + $ref: '#/components/schemas/BillingMetrics' +components: + schemas: + Invoice: + type: object + properties: + id: { type: integer } + total: { type: number } + BillingMetrics: + type: object + properties: + queueDepth: { type: integer } +`; + +const HIDE_USERS = `openapi: 3.0.3 +info: + title: Users API + version: 1.0.0 +tags: + - name: users + - name: staff +paths: + /users: + get: + tags: [users] + summary: List users + responses: + '200': + description: Users + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/User' + /internal/metrics: + get: + summary: Users metrics + responses: + '200': + description: Metrics + /users/{id}/audit: + parameters: + - name: id + in: path + required: true + schema: { type: integer } + get: + tags: [staff] + x-internal: true + summary: Audit trail + responses: + '200': + description: Audit entries + content: + application/json: + schema: + $ref: '#/components/schemas/AuditEntry' +components: + schemas: + User: + type: object + properties: + id: { type: integer } + email: { type: string } + AuditEntry: + type: object + properties: + actor: { type: string } +`; + export const EXAMPLES: Example[] = [ { id: 'rename', @@ -342,6 +444,34 @@ sources: { name: 'specs/schemas/author.yaml', content: MULTI_AUTHOR }, ], }, + { + id: 'hide-internal', + title: 'Hide internal endpoints', + config: `# Build a public spec: drop operations by path, tag or an x- flag. +# Both services expose /internal/metrics, which would normally conflict; +# filtered operations are removed before merging, along with the schemas, +# tags and security schemes only they used. +sources: + - name: billing + path: ./specs/billing.yaml + - name: users + path: ./specs/users.yaml + +merge: + filter: + exclude: + paths: ["/internal/**"] + tags: [internal] + extensions: [x-internal] + info: + title: Public API + version: 1.0.0 +`, + files: [ + { name: 'specs/billing.yaml', content: HIDE_BILLING }, + { name: 'specs/users.yaml', content: HIDE_USERS }, + ], + }, { id: 'remote', title: 'Remote URL + local file', diff --git a/web/tests/examples.test.ts b/web/tests/examples.test.ts index fa7a656..f14d74f 100644 --- a/web/tests/examples.test.ts +++ b/web/tests/examples.test.ts @@ -73,6 +73,22 @@ describe('examples', () => { expect(result.text).not.toMatch(/\.yaml#/); }); + it('hide-internal example removes internal endpoints and everything only they used', async () => { + const ex = findExample('hide-internal'); + expect(ex.id).toBe('hide-internal'); + const result = await runPipeline(ex.config, ex.files, { parseConfig, aggregate, pendingRefs, load: noNetwork }); + expect(result.problems).toEqual([]); + const text = result.text!; + expect(text).toContain('/invoices:'); + expect(text).toContain('/users:'); + expect(text).not.toContain('/internal'); + expect(text).not.toContain('/debug'); + expect(text).not.toContain('/audit'); + expect(text).not.toMatch(/internal/i); + expect(text).not.toContain('AuditEntry'); + expect(text).not.toContain('Metrics'); + }); + it('per-operation example combines GET and POST on one path', async () => { const ex = findExample('per-operation'); const { contents } = await resolveSources(parseConfig(ex.config).sources, ex.files, noNetwork); From 540d0363d62641d410b7323bc2337a7d33454b6c Mon Sep 17 00:00:00 2001 From: includeamin Date: Sun, 22 Nov 2026 00:54:39 +0100 Subject: [PATCH 7/7] docs: document operation filtering --- README.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/README.md b/README.md index b38c428..b33ec6f 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,7 @@ Available as both a **Rust library** and a **CLI tool**. - **Swagger 2.0 support** – Swagger 2.0 sources are converted to OpenAPI 3.0.3 automatically; anything that had to be approximated is reported as a warning - **External `$ref`s** – specs split across files or URLs are bundled per source before merging (CLI sandboxed to the config directory) - **Validation and CI check** – `--check` validates the merged spec and fails the build when it is invalid or when a committed output file is stale +- **Operation filters** – hide internal endpoints (by path glob, tag, `operationId` or an `x-` flag), globally or per source, with unused components and tags pruned - **Multiple source types** – local YAML files, local JSON files, and HTTP endpoints (with custom headers) - **Config-file driven** – define sources and merge options in a single YAML config - **Conflict resolution** – choose between `error`, `overwrite`, or `rename` strategies for duplicate paths and component names @@ -189,6 +190,32 @@ Example GitHub Actions step that keeps a committed spec in sync: The same validator is available as `openapi_aggregator::validate(&spec)`, and the playground shows its findings in the problems panel. +## Hiding internal endpoints + +Build a public spec from sources that also describe internal endpoints by filtering operations out. Filters run **per source, before the merge**, so a hidden operation can never cause a path or component conflict (two services can both expose `/internal/metrics`). + +```yaml +merge: + filter: # applies to every source + exclude: + paths: ["/internal/**", "/admin/*"] + tags: [internal] + operation_ids: [debugDump] + extensions: [x-internal] # truthy on the operation or its path item +sources: + - name: billing + path: billing.yaml + filter: # this source only + include: + tags: [public] # allow-list: keep only these operations +``` + +- **Rules:** an operation matches a rule if *any* of its criteria match (`paths`, `tags`, `operation_ids`, `extensions`). Nothing is hidden by default; list `x-internal` explicitly if you use it. +- **Combining:** `exclude` rules from the global and source level all apply, and `exclude` wins over `include`. `include` is an allow-list; when both levels define one, an operation must satisfy both. +- **Globs:** `*` matches within one path segment (`/admin/*` does not match `/admin/a/b`), `**` matches across segments (`/internal/**`). Everything else, including `{id}`, is literal. Globs apply to `paths` only, not `webhooks`. +- **Cleanup:** a path left with no operations is removed. Components (schemas, parameters, responses, ...), security schemes and tags that were used before filtering and are unused afterwards are pruned. Things that were never referenced to begin with are left alone. +- **Not scrubbed:** the filter does not look inside descriptions, examples, `servers`, `info` or vendor extensions, so check those for internal details yourself. External documents referenced only by hidden operations are still loaded. + ## Library Usage ```rust