diff --git a/README.md b/README.md index 71159e0..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 @@ -202,6 +229,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 +239,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/filter.rs b/crates/openapi-aggregator-core/src/filter.rs new file mode 100644 index 0000000..651afd1 --- /dev/null +++ b/crates/openapi-aggregator-core/src/filter.rs @@ -0,0 +1,848 @@ +//! 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 std::collections::HashSet; + +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, + } +} + +/// 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))) +} + +/// 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 +} + +/// 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::*; + 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!({}))); + } + + 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"] + ); + } + + 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 7576b61..8dde525 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; @@ -48,12 +49,14 @@ 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 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 cbf7a3c..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(); @@ -172,6 +198,7 @@ mod tests { } } })), + filter: None, }; let base = r#"{ @@ -200,6 +227,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 +254,7 @@ mod tests { path: PathBuf::from("ignored.yaml"), tag_prefix: None, additional_blocks: blocks, + filter: None, } } @@ -282,6 +311,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":{}}"#; @@ -366,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 1884ed3..0eb5796 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(), @@ -806,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"]); +} 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);