diff --git a/README.md b/README.md index ac3de2e..cce5cd8 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # openapi-aggregator -Aggregate and merge OpenAPI 3.x specifications from multiple sources into a single spec. +Aggregate and merge OpenAPI 3.x (and Swagger 2.0) specifications from multiple sources into a single spec. Available as both a **Rust library** and a **CLI tool**. @@ -8,6 +8,7 @@ Available as both a **Rust library** and a **CLI tool**. ## Features +- **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 - **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 @@ -197,6 +198,7 @@ Other top-level fields: - `webhooks` (OpenAPI 3.1) are merged like paths. - Top-level `security` stays top-level only when every source declares the same requirements. Otherwise each source's requirements are copied onto its own operations, so no operation gains or loses authentication. Renamed security schemes and `discriminator.mapping` entries are updated along with `$ref`s. +- Swagger 2.0 sources are converted to OpenAPI 3.0.3 before merging (`host`/`basePath`/`schemes` become `servers`, `in: body` and `in: formData` parameters become `requestBody`, `definitions` move to `components`, and so on). Conversion is lenient and each approximation or dropped field is reported as a warning prefixed with the source name. Swagger 1.x is not supported. - The merged `openapi` version comes from the first source. The CLI prints a warning when sources use different `major.minor` versions (also available via `aggregate_with_report`). - Component types are always emitted in the same order, so the output is stable across runs. diff --git a/crates/openapi-aggregator-core/src/lib.rs b/crates/openapi-aggregator-core/src/lib.rs index f5e1080..3dcb72e 100644 --- a/crates/openapi-aggregator-core/src/lib.rs +++ b/crates/openapi-aggregator-core/src/lib.rs @@ -39,6 +39,7 @@ pub mod config; pub mod error; pub mod merge; pub mod prepare; +pub mod swagger2; pub use config::{ Config, ConflictStrategy, InfoOverride, MergeConfig, OutputConfig, OutputFormat, ServerEntry, @@ -46,4 +47,4 @@ pub use config::{ }; pub use error::Error; pub use merge::{merge_specs, merge_specs_with_report, MergeReport}; -pub use prepare::{parse_content, prepare_source}; +pub use prepare::{parse_content, prepare_source, prepare_source_with_notes, PreparedSource}; diff --git a/crates/openapi-aggregator-core/src/prepare.rs b/crates/openapi-aggregator-core/src/prepare.rs index beee319..dd49cbc 100644 --- a/crates/openapi-aggregator-core/src/prepare.rs +++ b/crates/openapi-aggregator-core/src/prepare.rs @@ -3,18 +3,42 @@ use serde_json::Value; use crate::config::Source; use crate::error::Error; use crate::merge::deep_merge; +use crate::swagger2; -/// Parse spec text, apply the source's `additional_blocks` and validate it. -/// Returns `(display_name, spec)`. +/// A source after parsing, Swagger 2.0 conversion, `additional_blocks` and validation. +#[derive(Debug, Clone)] +pub struct PreparedSource { + pub name: String, + pub spec: Value, + /// Warnings about anything approximated while converting from Swagger 2.0, + /// each prefixed with `source '': `. Empty for OpenAPI 3.x sources. + pub notes: Vec, +} + +/// Parse spec text, convert Swagger 2.0 to OpenAPI 3.0, apply the source's +/// `additional_blocks` and validate it. Returns `(display_name, spec)`. pub fn prepare_source(content: &str, source: &Source) -> Result<(String, Value), Error> { + prepare_source_with_notes(content, source).map(|p| (p.name, p.spec)) +} + +/// Like [`prepare_source`], but also returns the conversion notes. +pub fn prepare_source_with_notes(content: &str, source: &Source) -> Result { let name = source.display_name(); - let value = parse_and_prepare(content, source)?; - validate_openapi(&value, &name)?; - Ok((name, value)) + let (spec, notes) = parse_and_prepare(content, source)?; + validate_openapi(&spec, &name)?; + let notes = notes + .into_iter() + .map(|n| format!("source '{name}': {n}")) + .collect(); + Ok(PreparedSource { name, spec, notes }) } -fn parse_and_prepare(content: &str, source: &Source) -> Result { +fn parse_and_prepare(content: &str, source: &Source) -> Result<(Value, Vec), Error> { let mut value = parse_content(content)?; + let mut notes = Vec::new(); + if is_swagger2(&value) { + (value, notes) = swagger2::convert(value); + } if let Some(blocks) = source_additional_blocks(source) { if !blocks.is_object() { return Err(Error::InvalidSpec { @@ -24,7 +48,19 @@ fn parse_and_prepare(content: &str, source: &Source) -> Result { } deep_merge(&mut value, blocks); } - Ok(value) + Ok((value, notes)) +} + +/// A Swagger 2.0 document: has `swagger: 2.x` (string or bare YAML number) and no `openapi`. +fn is_swagger2(value: &Value) -> bool { + if value.get("openapi").is_some() { + return false; + } + match value.get("swagger") { + Some(Value::String(v)) => v == "2" || v.starts_with("2."), + Some(Value::Number(n)) => n.as_f64() == Some(2.0), + _ => false, + } } fn source_additional_blocks(source: &Source) -> Option<&Value> { @@ -56,7 +92,7 @@ fn validate_openapi(value: &Value, source_name: &str) -> Result<(), Error> { }), None if value.get("swagger").is_some() => Err(Error::InvalidSpec { name: source_name.into(), - reason: "Swagger 2.0 specs are not supported (only OpenAPI 3.x is supported)".into(), + reason: "Swagger 1.x is not supported (only Swagger 2.0 and OpenAPI 3.x are)".into(), }), None => Err(Error::InvalidSpec { name: source_name.into(), @@ -125,7 +161,7 @@ mod tests { } }"#; - let merged = parse_and_prepare(base, &source).unwrap(); + let merged = parse_and_prepare(base, &source).unwrap().0; assert_eq!(merged["x-vendor-root"]["enabled"], true); assert_eq!(merged["paths"]["/pets"]["get"]["summary"], "list pets"); assert_eq!( @@ -152,18 +188,68 @@ mod tests { } #[test] - fn prepare_source_rejects_non_openapi_with_source_name() { - let source = Source::File { - name: Some("legacy".into()), - path: PathBuf::from("ignored.yaml"), - tag_prefix: None, - additional_blocks: None, - }; - let err = prepare_source("swagger: '2.0'\ninfo: {title: T, version: '1'}\n", &source) + fn prepare_source_rejects_swagger_1_x_with_source_name() { + let source = file_source("legacy", None); + let err = prepare_source("swagger: '1.2'\ninfo: {title: T, version: '1'}\n", &source) .unwrap_err() .to_string(); assert!(err.contains("legacy"), "{err}"); - assert!(err.contains("Swagger 2.0") && err.contains("3.x"), "{err}"); + assert!(err.contains("Swagger 1.x"), "{err}"); + } + + fn file_source(name: &str, blocks: Option) -> Source { + Source::File { + name: Some(name.into()), + path: PathBuf::from("ignored.yaml"), + tag_prefix: None, + additional_blocks: blocks, + } + } + + const SWAGGER2: &str = + "swagger: '2.0'\ninfo: {title: T, version: '1'}\nhost: api.test\npaths: {}\n"; + + #[test] + fn prepare_converts_swagger2_and_prefixes_notes() { + let prepared = prepare_source_with_notes(SWAGGER2, &file_source("legacy", None)).unwrap(); + assert_eq!(prepared.name, "legacy"); + assert_eq!(prepared.spec["openapi"], "3.0.3"); + assert!(!prepared.notes.is_empty()); + assert!(prepared + .notes + .iter() + .all(|n| n.starts_with("source 'legacy': "))); + assert!(prepared.notes[0].contains("converted from Swagger 2.0")); + + let (name, spec) = prepare_source(SWAGGER2, &file_source("legacy", None)).unwrap(); + assert_eq!( + (name.as_str(), &spec["openapi"]), + ("legacy", &json!("3.0.3")) + ); + } + + #[test] + fn plain_openapi_has_no_notes() { + let prepared = prepare_source_with_notes( + r#"{"openapi":"3.0.3","info":{"title":"T","version":"1"},"paths":{}}"#, + &file_source("x", None), + ) + .unwrap(); + assert!(prepared.notes.is_empty()); + } + + #[test] + fn additional_blocks_apply_after_conversion() { + let blocks = + json!({"info": {"x-a": 1}, "components": {"schemas": {"Extra": {"type": "object"}}}}); + let prepared = + prepare_source_with_notes(SWAGGER2, &file_source("legacy", Some(blocks))).unwrap(); + assert_eq!(prepared.spec["info"]["x-a"], 1); + assert_eq!( + prepared.spec["components"]["schemas"]["Extra"]["type"], + "object" + ); + assert_eq!(prepared.spec["servers"][0]["url"], "https://api.test"); } #[test] diff --git a/crates/openapi-aggregator-core/src/swagger2.rs b/crates/openapi-aggregator-core/src/swagger2.rs new file mode 100644 index 0000000..b65d0af --- /dev/null +++ b/crates/openapi-aggregator-core/src/swagger2.rs @@ -0,0 +1,1032 @@ +//! Convert Swagger 2.0 documents to OpenAPI 3.0.3. + +use serde_json::{Map, Value}; + +/// Convert a Swagger 2.0 document to OpenAPI 3.0.3. +/// +/// Returns the converted spec and human-readable notes describing anything that was +/// approximated or dropped. Never fails: odd input is passed through. +pub fn convert(spec: Value) -> (Value, Vec) { + let Value::Object(mut root) = spec else { + return (spec, Vec::new()); + }; + let mut notes = vec!["converted from Swagger 2.0 to OpenAPI 3.0.3".to_string()]; + let mut components = Map::new(); + + root.remove("swagger"); + let mut out = Map::new(); + out.insert("openapi".into(), Value::String("3.0.3".into())); + + if let Some(servers) = build_servers(&mut root) { + notes.push("host/basePath/schemes moved into servers".into()); + out.insert("servers".into(), servers); + } + + if let Some(Value::Object(mut defs)) = root.remove("definitions") { + for schema in defs.values_mut() { + fix_schema(schema); + } + components.insert("schemas".into(), Value::Object(defs)); + } + let top_responses = root.remove("responses"); + if let Some(Value::Object(schemes)) = root.remove("securityDefinitions") { + let schemes = schemes + .into_iter() + .map(|(name, scheme)| (name, convert_security_scheme(scheme, &mut notes))) + .collect(); + components.insert("securitySchemes".into(), Value::Object(schemes)); + } + + let root_consumes = string_list(root.remove("consumes")); + let root_produces = string_list(root.remove("produces")); + + let top_params = match root.remove("parameters") { + Some(Value::Object(m)) => m, + _ => Map::new(), + }; + let mut ctx = Ctx { + top_params: &top_params, + root_consumes: &root_consumes, + root_produces: &root_produces, + notes: &mut notes, + }; + if let Some(Value::Object(responses)) = top_responses { + let converted = responses + .into_iter() + .map(|(name, r)| (name, convert_response(r, ctx.root_produces))) + .collect(); + components.insert("responses".into(), Value::Object(converted)); + } + let (params, bodies) = ctx.convert_top_level_parameters(); + if !params.is_empty() { + components.insert("parameters".into(), Value::Object(params)); + } + if !bodies.is_empty() { + components.insert("requestBodies".into(), Value::Object(bodies)); + } + if let Some(Value::Object(paths)) = root.get_mut("paths") { + for (path, item) in paths.iter_mut() { + ctx.convert_path_item(path, item); + } + } + + for (key, value) in root { + out.insert(key, value); + } + if !components.is_empty() { + out.insert("components".into(), Value::Object(components)); + } + + let mut out = Value::Object(out); + rewrite_refs(&mut out); + (out, notes) +} + +const METHODS: [&str; 8] = [ + "get", "put", "post", "delete", "options", "head", "patch", "trace", +]; + +/// Keys of a Swagger 2.0 non-body parameter that belong in the 3.0 `schema`. +const SCHEMA_KEYS: [&str; 14] = [ + "type", + "format", + "items", + "enum", + "default", + "minimum", + "maximum", + "exclusiveMinimum", + "exclusiveMaximum", + "minLength", + "maxLength", + "pattern", + "minItems", + "maxItems", +]; + +fn string_list(value: Option) -> Vec { + match value { + Some(Value::Array(items)) => items + .into_iter() + .filter_map(|v| v.as_str().map(String::from)) + .collect(), + _ => Vec::new(), + } +} + +/// A classified Swagger 2.0 parameter. +enum Param { + /// Non-body, non-form: stays a parameter (already converted or a `$ref`). + Plain(Value), + /// `in: body`: the finished 3.0 `requestBody`. + Body(Value), + /// `in: formData`: the raw 2.0 parameter. + Form(Map), +} + +struct Ctx<'a> { + top_params: &'a Map, + root_consumes: &'a [String], + root_produces: &'a [String], + notes: &'a mut Vec, +} + +impl Ctx<'_> { + fn convert_top_level_parameters(&mut self) -> (Map, Map) { + let mut params = Map::new(); + let mut bodies = Map::new(); + for (name, raw) in self.top_params { + match self.classify(raw.clone(), &[], "") { + Param::Plain(p) => { + params.insert(name.clone(), p); + } + Param::Body(b) => { + bodies.insert(name.clone(), b); + } + Param::Form(_) => {} + } + } + (params, bodies) + } + + fn classify(&mut self, raw: Value, consumes: &[String], ctx_label: &str) -> Param { + let Value::Object(mut map) = raw else { + return Param::Plain(raw); + }; + if let Some(Value::String(target)) = map.get("$ref") { + let referenced = target + .strip_prefix("#/parameters/") + .and_then(|name| self.top_params.get(name).map(|p| (name.to_string(), p))); + if let Some((name, Value::Object(p))) = referenced { + match p.get("in").and_then(Value::as_str) { + Some("body") => { + return Param::Body( + serde_json::json!({"$ref": format!("#/components/requestBodies/{name}")}), + ) + } + Some("formData") => return Param::Form(p.clone()), + _ => {} + } + } + return Param::Plain(Value::Object(map)); + } + match map.get("in").and_then(Value::as_str) { + Some("body") => { + let consumes = if consumes.is_empty() { + self.root_consumes + } else { + consumes + }; + Param::Body(build_request_body(map, consumes)) + } + Some("formData") => Param::Form(map), + _ => { + self.convert_plain_parameter(&mut map, ctx_label); + Param::Plain(Value::Object(map)) + } + } + } + + /// Move schema-ish keys into `schema` and map `collectionFormat` to `style`/`explode`. + fn convert_plain_parameter(&mut self, param: &mut Map, ctx_label: &str) { + let mut schema = take_schema_keys(param); + self.strip_nested_collection_format(&mut schema, ctx_label); + let location = param + .get("in") + .and_then(Value::as_str) + .unwrap_or("") + .to_string(); + let collection = param + .remove("collectionFormat") + .and_then(|v| v.as_str().map(String::from)); + if schema.get("type").and_then(Value::as_str) == Some("array") { + let format = collection.as_deref().unwrap_or("csv"); + let style = match (format, location.as_str()) { + ("csv", "query" | "cookie") => Some(("form", false)), + ("csv", "path" | "header") => Some(("simple", false)), + ("multi", "query") => Some(("form", true)), + ("ssv", "query") => Some(("spaceDelimited", false)), + ("pipes", "query") => Some(("pipeDelimited", false)), + _ => None, + }; + match style { + Some((style, explode)) => { + param.insert("style".into(), style.into()); + param.insert("explode".into(), explode.into()); + } + None => self.notes.push(format!( + "collectionFormat '{format}' is not supported in OpenAPI 3; dropped" + )), + } + } + let mut schema = Value::Object(schema); + fix_schema(&mut schema); + param.insert("schema".into(), schema); + } + + fn strip_nested_collection_format(&mut self, schema: &mut Map, ctx_label: &str) { + let mut current = schema.get_mut("items"); + while let Some(Value::Object(items)) = current { + if items.remove("collectionFormat").is_some() { + self.notes.push(format!( + "collectionFormat on nested array items{ctx_label} is not supported in OpenAPI 3; dropped" + )); + } + current = items.get_mut("items"); + } + } + + fn convert_path_item(&mut self, path: &str, item: &mut Value) { + let Value::Object(item) = item else { return }; + + let path_params: Vec = match item.remove("parameters") { + Some(Value::Array(list)) => list + .into_iter() + .map(|p| self.classify(p, &[], &format!(" on {path}"))) + .collect(), + Some(other) => { + item.insert("parameters".into(), other); + Vec::new() + } + None => Vec::new(), + }; + let mut shared_plain = Vec::new(); + let mut shared_body_form = Vec::new(); + for p in path_params { + match p { + Param::Plain(v) => shared_plain.push(v), + other => shared_body_form.push(other), + } + } + if !shared_plain.is_empty() { + item.insert("parameters".into(), Value::Array(shared_plain)); + } + + for method in METHODS { + if let Some(Value::Object(op)) = item.get_mut(method) { + let label = format!("{} {path}", method.to_uppercase()); + self.convert_operation(&label, op, &shared_body_form); + } + } + } + + fn convert_operation( + &mut self, + label: &str, + op: &mut Map, + shared_body_form: &[Param], + ) { + let consumes = string_list(op.remove("consumes")); + let produces = match op.remove("produces") { + Some(v) => string_list(Some(v)), + None => self.root_produces.to_vec(), + }; + if let Some(Value::Object(responses)) = op.get_mut("responses") { + for response in responses.values_mut() { + *response = convert_response(response.take(), &produces); + } + } + let own: Vec = match op.remove("parameters") { + Some(Value::Array(list)) => list + .into_iter() + .map(|p| self.classify(p, &consumes, &format!(" on {label}"))) + .collect(), + Some(other) => { + op.insert("parameters".into(), other); + Vec::new() + } + None => Vec::new(), + }; + let mut plain = Vec::new(); + let mut bodies = Vec::new(); + let mut forms = Vec::new(); + for p in own { + match p { + Param::Plain(v) => plain.push(v), + Param::Body(b) => bodies.push(b), + Param::Form(f) => forms.push(f), + } + } + if bodies.is_empty() && forms.is_empty() { + for p in shared_body_form { + match p { + Param::Body(b) => bodies.push(b.clone()), + Param::Form(f) => forms.push(f.clone()), + Param::Plain(_) => {} + } + } + } + if !plain.is_empty() { + op.insert("parameters".into(), Value::Array(plain)); + } + if bodies.len() > 1 { + self.notes.push(format!( + "multiple 'in: body' parameters on {label}; kept the first" + )); + } + if !bodies.is_empty() && !forms.is_empty() { + self.notes.push(format!( + "'in: body' and 'in: formData' parameters on {label}; kept the body" + )); + } + let request_body = if let Some(body) = bodies.into_iter().next() { + Some(body) + } else if !forms.is_empty() { + let consumes = if consumes.is_empty() { + self.root_consumes + } else { + &consumes + }; + let (body, media) = build_form_body(forms, consumes); + self.notes.push(format!( + "formData parameters on {label} converted to {media} request body" + )); + Some(body) + } else { + None + }; + if let Some(body) = request_body { + op.insert("requestBody".into(), body); + } + } +} + +/// Remove the schema-related keys from a parameter and return them as a schema map. +fn take_schema_keys(param: &mut Map) -> Map { + let mut schema = Map::new(); + for key in SCHEMA_KEYS { + if let Some(v) = param.remove(key) { + schema.insert(key.into(), v); + } + } + schema +} + +fn media_types(consumes: &[String]) -> Vec { + if consumes.is_empty() { + vec!["application/json".to_string()] + } else { + consumes.to_vec() + } +} + +fn build_request_body(mut param: Map, consumes: &[String]) -> Value { + let mut schema = param + .remove("schema") + .unwrap_or_else(|| serde_json::json!({})); + fix_schema(&mut schema); + let content: Map = media_types(consumes) + .into_iter() + .map(|m| (m, serde_json::json!({ "schema": schema.clone() }))) + .collect(); + let mut body = Map::new(); + for key in ["description", "required"] { + if let Some(v) = param.remove(key) { + body.insert(key.into(), v); + } + } + body.insert("content".into(), Value::Object(content)); + Value::Object(body) +} + +/// Build a form request body; returns it with the media type used. +fn build_form_body(forms: Vec>, consumes: &[String]) -> (Value, &'static str) { + let has_file = forms + .iter() + .any(|f| f.get("type").and_then(Value::as_str) == Some("file")); + let multipart = has_file || consumes.iter().any(|c| c == "multipart/form-data"); + let media = if multipart { + "multipart/form-data" + } else { + "application/x-www-form-urlencoded" + }; + let mut properties = Map::new(); + let mut required = Vec::new(); + for mut form in forms { + let Some(name) = form.get("name").and_then(Value::as_str).map(String::from) else { + continue; + }; + if form.get("required") == Some(&Value::Bool(true)) { + required.push(Value::String(name.clone())); + } + let mut schema = take_schema_keys(&mut form); + if let Some(Value::String(d)) = form.remove("description") { + schema.insert("description".into(), Value::String(d)); + } + form.remove("collectionFormat"); + let mut schema = Value::Object(schema); + fix_schema(&mut schema); + properties.insert(name, schema); + } + let mut schema = serde_json::json!({"type": "object", "properties": properties}); + let has_required = !required.is_empty(); + if has_required { + schema["required"] = Value::Array(required); + } + let mut body = serde_json::json!({"content": {media: {"schema": schema}}}); + if has_required { + body["required"] = Value::Bool(true); + } + (body, media) +} + +/// Convert a Swagger 2.0 response object (`schema`, `headers`, `examples`) to 3.0. +fn convert_response(response: Value, produces: &[String]) -> Value { + let Value::Object(mut map) = response else { + return response; + }; + if map.contains_key("$ref") { + return Value::Object(map); + } + let mut content: Map = Map::new(); + if let Some(mut schema) = map.remove("schema") { + fix_schema(&mut schema); + for media in media_types(produces) { + content.insert(media, serde_json::json!({ "schema": schema.clone() })); + } + } + if let Some(Value::Object(examples)) = map.remove("examples") { + for (media, example) in examples { + let entry = content + .entry(media) + .or_insert_with(|| Value::Object(Map::new())); + if let Value::Object(entry) = entry { + entry.insert("example".into(), example); + } + } + } + if !content.is_empty() { + map.insert("content".into(), Value::Object(content)); + } + if let Some(Value::Object(headers)) = map.get_mut("headers") { + for header in headers.values_mut() { + if let Value::Object(h) = header { + let mut schema = Value::Object(take_schema_keys(h)); + h.remove("collectionFormat"); + fix_schema(&mut schema); + h.insert("schema".into(), schema); + } + } + } + Value::Object(map) +} + +fn convert_security_scheme(scheme: Value, notes: &mut Vec) -> Value { + let Value::Object(mut map) = scheme else { + return scheme; + }; + match map.get("type").and_then(Value::as_str) { + Some("basic") => { + map.insert("type".into(), "http".into()); + map.insert("scheme".into(), "basic".into()); + } + Some("apiKey") => {} + Some("oauth2") => { + let flow = map + .remove("flow") + .and_then(|v| v.as_str().map(String::from)); + let (target, keys): (&str, &[&str]) = match flow.as_deref() { + Some("implicit") => ("implicit", &["authorizationUrl"]), + Some("password") => ("password", &["tokenUrl"]), + Some("application") => ("clientCredentials", &["tokenUrl"]), + Some("accessCode") => ("authorizationCode", &["authorizationUrl", "tokenUrl"]), + other => { + notes.push(format!( + "unknown OAuth2 flow '{}' passed through", + other.unwrap_or("") + )); + return Value::Object(map); + } + }; + let mut flow_obj = Map::new(); + for key in keys { + if let Some(v) = map.remove(*key) { + flow_obj.insert((*key).into(), v); + } + } + let scopes = map + .remove("scopes") + .unwrap_or_else(|| Value::Object(Map::new())); + flow_obj.insert("scopes".into(), scopes); + map.insert("flows".into(), serde_json::json!({ target: flow_obj })); + } + other => notes.push(format!( + "unknown security scheme type '{}' passed through", + other.unwrap_or("") + )), + } + Value::Object(map) +} + +/// Build `servers` from `host`, `basePath` and `schemes`, removing those keys. +fn build_servers(root: &mut Map) -> Option { + let host = root.remove("host"); + let base_path = root.remove("basePath"); + let schemes = root.remove("schemes"); + let host = host + .as_ref() + .and_then(Value::as_str) + .filter(|h| !h.is_empty()); + let base = base_path.as_ref().and_then(Value::as_str).unwrap_or(""); + let urls: Vec = match host { + Some(host) => { + let schemes: Vec<&str> = schemes + .as_ref() + .and_then(Value::as_array) + .map(|a| a.iter().filter_map(Value::as_str).collect()) + .filter(|v: &Vec<&str>| !v.is_empty()) + .unwrap_or_else(|| vec!["https"]); + schemes + .iter() + .map(|s| format!("{s}://{host}{base}")) + .collect() + } + None if !base.is_empty() => vec![base.to_string()], + None => return None, + }; + Some(Value::Array( + urls.into_iter() + .map(|url| serde_json::json!({ "url": url })) + .collect(), + )) +} + +/// Apply Swagger 2.0 -> 3.0 schema keyword fixes, recursing through schema-structural keys only. +fn fix_schema(schema: &mut Value) { + let Value::Object(map) = schema else { return }; + if map.get("type").and_then(Value::as_str) == Some("file") { + map.insert("type".into(), "string".into()); + map.insert("format".into(), "binary".into()); + } + if map.get("x-nullable") == Some(&Value::Bool(true)) { + map.remove("x-nullable"); + map.insert("nullable".into(), Value::Bool(true)); + } + if let Some(Value::String(name)) = map.get("discriminator") { + let name = name.clone(); + map.insert( + "discriminator".into(), + serde_json::json!({ "propertyName": name }), + ); + } + if let Some(Value::Object(props)) = map.get_mut("properties") { + props.values_mut().for_each(fix_schema); + } + for key in ["items", "additionalProperties", "not"] { + if let Some(v) = map.get_mut(key) { + fix_schema(v); + } + } + for key in ["allOf", "anyOf", "oneOf"] { + if let Some(Value::Array(items)) = map.get_mut(key) { + items.iter_mut().for_each(fix_schema); + } + } +} + +/// Rewrite Swagger 2.0 `$ref` targets (and `discriminator.mapping` values) to their +/// OpenAPI 3 locations, anywhere in the document. +pub(crate) fn rewrite_refs(value: &mut Value) { + match value { + Value::Object(map) => { + for (key, v) in map.iter_mut() { + match v { + Value::String(s) if key == "$ref" => *s = rewrite_ref(s), + Value::Object(mapping) if key == "mapping" => { + for target in mapping.values_mut() { + if let Value::String(s) = target { + *s = rewrite_ref(s); + } + } + } + _ => rewrite_refs(v), + } + } + } + Value::Array(items) => items.iter_mut().for_each(rewrite_refs), + _ => {} + } +} + +fn rewrite_ref(target: &str) -> String { + for (old, new) in [ + ("#/definitions/", "#/components/schemas/"), + ("#/parameters/", "#/components/parameters/"), + ("#/responses/", "#/components/responses/"), + ] { + if let Some(rest) = target.strip_prefix(old) { + return format!("{new}{rest}"); + } + } + target.to_string() +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + + fn conv(v: Value) -> (Value, Vec) { + convert(v) + } + + #[test] + fn converts_version_and_info() { + let (out, notes) = + conv(json!({"swagger":"2.0","info":{"title":"T","version":"1"},"paths":{}})); + assert_eq!(out["openapi"], "3.0.3"); + assert_eq!(out["info"], json!({"title":"T","version":"1"})); + assert!(out.get("swagger").is_none()); + assert!(notes.contains(&"converted from Swagger 2.0 to OpenAPI 3.0.3".to_string())); + } + + #[test] + fn builds_servers_from_host_basepath_schemes() { + let (out, notes) = conv( + json!({"swagger":"2.0","host":"api.test","basePath":"/v1","schemes":["https","http"]}), + ); + assert_eq!( + out["servers"], + json!([{"url":"https://api.test/v1"},{"url":"http://api.test/v1"}]) + ); + assert!( + out.get("host").is_none() + && out.get("basePath").is_none() + && out.get("schemes").is_none() + ); + assert!(notes.iter().any(|n| n.contains("servers"))); + + let (out, _) = conv(json!({"swagger":"2.0","host":"api.test"})); + assert_eq!(out["servers"], json!([{"url":"https://api.test"}])); + let (out, _) = conv(json!({"swagger":"2.0","basePath":"/v1"})); + assert_eq!(out["servers"], json!([{"url":"/v1"}])); + let (out, notes) = conv(json!({"swagger":"2.0"})); + assert!(out.get("servers").is_none()); + assert!(!notes.iter().any(|n| n.contains("servers"))); + } + + #[test] + fn moves_definitions_to_components_schemas_and_rewrites_refs() { + let (out, _) = conv(json!({ + "swagger":"2.0", + "definitions":{ + "Pet":{"type":"object","properties":{ + "friends":{"type":"array","items":{"$ref":"#/definitions/Pet"}}, + "owner":{"allOf":[{"$ref":"#/definitions/Owner"}]}, + "meta":{"type":"object","additionalProperties":{"$ref":"#/definitions/Owner"}}}}, + "Owner":{"type":"object","discriminator":"kind","properties":{"kind":{"type":"string"}}} + }, + "paths":{"/pets":{"get":{"responses":{"200":{"description":"ok","schema":{"$ref":"#/definitions/Pet"}}}}}} + })); + assert!(out.get("definitions").is_none()); + let pet = &out["components"]["schemas"]["Pet"]["properties"]; + assert_eq!(pet["friends"]["items"]["$ref"], "#/components/schemas/Pet"); + assert_eq!( + pet["owner"]["allOf"][0]["$ref"], + "#/components/schemas/Owner" + ); + assert_eq!( + pet["meta"]["additionalProperties"]["$ref"], + "#/components/schemas/Owner" + ); + assert!(!out.to_string().contains("#/definitions/")); + } + + #[test] + fn discriminator_mapping_refs_are_rewritten() { + let (out, _) = conv(json!({"swagger":"2.0","definitions":{ + "A":{"discriminator":{"propertyName":"k","mapping":{"b":"#/definitions/B"}}},"B":{}}})); + assert_eq!( + out["components"]["schemas"]["A"]["discriminator"]["mapping"]["b"], + "#/components/schemas/B" + ); + } + + #[test] + fn schema_fixups() { + let (out, _) = conv(json!({"swagger":"2.0","definitions":{ + "F":{"type":"file"}, + "N":{"type":"string","x-nullable":true}, + "D":{"type":"object","discriminator":"kind"}, + "P":{"type":"object","properties":{"f":{"type":"file"}}}}})); + let s = &out["components"]["schemas"]; + assert_eq!(s["F"], json!({"type":"string","format":"binary"})); + assert_eq!(s["N"], json!({"type":"string","nullable":true})); + assert_eq!(s["D"]["discriminator"], json!({"propertyName":"kind"})); + assert_eq!( + s["P"]["properties"]["f"], + json!({"type":"string","format":"binary"}) + ); + } + + #[test] + fn tolerates_empty_and_odd_input() { + let (out, _) = conv(json!({"swagger":"2.0"})); + assert_eq!(out["openapi"], "3.0.3"); + let _ = + conv(json!({"swagger":"2.0","paths":[],"definitions":5,"host":7,"schemes":"https"})); + let _ = conv(json!("not an object")); + } + + fn op(v: Value) -> Value { + conv(json!({"swagger":"2.0","paths":{"/pets":{"post":v}}})).0["paths"]["/pets"]["post"] + .clone() + } + + #[test] + fn non_body_param_gets_schema() { + let o = op(json!({"parameters":[ + {"name":"limit","in":"query","type":"integer","format":"int32","minimum":1,"default":10,"description":"d","required":false}, + {"name":"tags","in":"query","type":"array","items":{"type":"string","enum":["a","b"]},"collectionFormat":"multi"} + ]})); + assert_eq!( + o["parameters"][0], + json!({"name":"limit","in":"query","description":"d","required":false, + "schema":{"type":"integer","format":"int32","minimum":1,"default":10}}) + ); + assert_eq!( + o["parameters"][1]["schema"], + json!({"type":"array","items":{"type":"string","enum":["a","b"]}}) + ); + } + + #[test] + fn collection_format_maps_to_style() { + let style = |cf: Option<&str>, loc: &str| { + let mut p = json!({"name":"x","in":loc,"type":"array","items":{"type":"string"}}); + if let Some(cf) = cf { + p["collectionFormat"] = json!(cf); + } + let (out, notes) = + conv(json!({"swagger":"2.0","paths":{"/p":{"get":{"parameters":[p]}}}})); + (out["paths"]["/p"]["get"]["parameters"][0].clone(), notes) + }; + let (p, _) = style(Some("csv"), "query"); + assert_eq!( + (&p["style"], &p["explode"]), + (&json!("form"), &json!(false)) + ); + let (p, _) = style(None, "query"); + assert_eq!( + (&p["style"], &p["explode"]), + (&json!("form"), &json!(false)) + ); + let (p, _) = style(Some("multi"), "query"); + assert_eq!((&p["style"], &p["explode"]), (&json!("form"), &json!(true))); + assert_eq!(style(Some("pipes"), "query").0["style"], "pipeDelimited"); + assert_eq!(style(Some("ssv"), "query").0["style"], "spaceDelimited"); + assert_eq!(style(Some("csv"), "path").0["style"], "simple"); + assert_eq!(style(Some("csv"), "header").0["style"], "simple"); + let (p, notes) = style(Some("tsv"), "query"); + assert!(p.get("style").is_none() && p.get("collectionFormat").is_none()); + assert!(notes + .iter() + .any(|n| n.contains("collectionFormat 'tsv' is not supported in OpenAPI 3; dropped"))); + } + + #[test] + fn body_param_becomes_request_body() { + let body = json!({"in":"body","name":"b","required":true,"description":"d","schema":{"$ref":"#/definitions/Pet"}}); + let o = op(json!({"consumes":["application/xml"],"parameters":[body.clone()]})); + assert_eq!( + o["requestBody"], + json!({"description":"d","required":true, + "content":{"application/xml":{"schema":{"$ref":"#/components/schemas/Pet"}}}}) + ); + assert!(o.get("parameters").is_none() && o.get("consumes").is_none()); + + let o = op(json!({"parameters":[body.clone()]})); + assert!(o["requestBody"]["content"] + .get("application/json") + .is_some()); + + let (out, _) = conv( + json!({"swagger":"2.0","consumes":["text/plain"],"paths":{"/p":{ + "post":{"parameters":[body.clone()]}, + "put":{"consumes":["application/xml"],"parameters":[body]}}}}), + ); + assert!(out["paths"]["/p"]["post"]["requestBody"]["content"] + .get("text/plain") + .is_some()); + assert!(out["paths"]["/p"]["put"]["requestBody"]["content"] + .get("application/xml") + .is_some()); + assert!(out.get("consumes").is_none()); + } + + #[test] + fn form_data_becomes_form_body() { + let o = op(json!({"parameters":[ + {"name":"a","in":"formData","type":"string","required":true}, + {"name":"b","in":"formData","type":"integer"}]})); + let c = &o["requestBody"]["content"]["application/x-www-form-urlencoded"]["schema"]; + assert_eq!(c["type"], "object"); + assert_eq!(c["properties"]["a"], json!({"type":"string"})); + assert_eq!(c["properties"]["b"], json!({"type":"integer"})); + assert_eq!(c["required"], json!(["a"])); + + let (out, notes) = conv( + json!({"swagger":"2.0","paths":{"/pets":{"post":{"parameters":[ + {"name":"f","in":"formData","type":"file"}]}}}}), + ); + let o = &out["paths"]["/pets"]["post"]; + assert_eq!( + o["requestBody"]["content"]["multipart/form-data"]["schema"]["properties"]["f"], + json!({"type":"string","format":"binary"}) + ); + assert!(notes.iter().any(|n| n.contains( + "formData parameters on POST /pets converted to multipart/form-data request body" + ))); + } + + #[test] + fn multiple_bodies_keep_first_with_note() { + let (out, notes) = conv( + json!({"swagger":"2.0","paths":{"/pets":{"post":{"parameters":[ + {"in":"body","name":"a","schema":{"type":"string"}}, + {"in":"body","name":"b","schema":{"type":"integer"}}]}}}}), + ); + let s = + &out["paths"]["/pets"]["post"]["requestBody"]["content"]["application/json"]["schema"]; + assert_eq!(s["type"], "string"); + assert!(notes + .iter() + .any(|n| n.contains("multiple 'in: body' parameters on POST /pets; kept the first"))); + } + + #[test] + fn body_and_form_keep_body_with_note() { + let (out, notes) = conv( + json!({"swagger":"2.0","paths":{"/pets":{"post":{"parameters":[ + {"in":"body","name":"a","schema":{"type":"string"}}, + {"in":"formData","name":"f","type":"string"}]}}}}), + ); + assert!(out["paths"]["/pets"]["post"]["requestBody"]["content"] + .get("application/json") + .is_some()); + assert!(notes.iter().any( + |n| n.contains("'in: body' and 'in: formData' parameters on POST /pets; kept the body") + )); + } + + #[test] + fn top_level_parameters_split() { + let (out, _) = conv(json!({"swagger":"2.0", + "parameters":{ + "Body":{"in":"body","name":"b","required":true,"schema":{"$ref":"#/definitions/Pet"}}, + "Limit":{"in":"query","name":"limit","type":"integer"}}, + "definitions":{"Pet":{}}, + "paths":{"/p":{"post":{"parameters":[{"$ref":"#/parameters/Body"},{"$ref":"#/parameters/Limit"}]}}}})); + assert!(out.get("parameters").is_none()); + assert_eq!( + out["components"]["parameters"]["Limit"]["schema"], + json!({"type":"integer"}) + ); + assert!(out["components"]["parameters"].get("Body").is_none()); + assert_eq!( + out["components"]["requestBodies"]["Body"]["content"]["application/json"]["schema"] + ["$ref"], + "#/components/schemas/Pet" + ); + let o = &out["paths"]["/p"]["post"]; + assert_eq!( + o["requestBody"], + json!({"$ref":"#/components/requestBodies/Body"}) + ); + assert_eq!( + o["parameters"], + json!([{"$ref":"#/components/parameters/Limit"}]) + ); + } + + #[test] + fn path_item_level_parameters_converted() { + let (out, _) = conv(json!({"swagger":"2.0","paths":{"/p/{id}":{ + "parameters":[{"name":"id","in":"path","required":true,"type":"string"}, + {"in":"body","name":"b","schema":{"type":"string"}}], + "get":{}, + "post":{"parameters":[{"in":"body","name":"own","schema":{"type":"integer"}}]}}}})); + let item = &out["paths"]["/p/{id}"]; + assert_eq!( + item["parameters"], + json!([{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]) + ); + assert_eq!( + item["get"]["requestBody"]["content"]["application/json"]["schema"]["type"], + "string" + ); + assert_eq!( + item["post"]["requestBody"]["content"]["application/json"]["schema"]["type"], + "integer" + ); + } + + fn resp_of(root: Value, op: Value) -> Value { + let mut spec = root; + spec["swagger"] = json!("2.0"); + spec["paths"] = json!({"/p":{"get":op}}); + convert(spec).0["paths"]["/p"]["get"]["responses"]["200"].clone() + } + + #[test] + fn response_schema_becomes_content() { + let r = resp_of( + json!({"produces":["application/json","application/xml"]}), + json!({"responses":{"200":{"description":"ok","schema":{"$ref":"#/definitions/Pet"}}}}), + ); + let want = json!({"schema":{"$ref":"#/components/schemas/Pet"}}); + assert_eq!( + r["content"], + json!({"application/json":want.clone(),"application/xml":want}) + ); + assert!(r.get("schema").is_none()); + + let r = resp_of( + json!({"produces":["application/json"]}), + json!({"produces":["text/plain"],"responses":{"200":{"description":"ok","schema":{"type":"string"}}}}), + ); + assert!( + r["content"].get("text/plain").is_some() + && r["content"].get("application/json").is_none() + ); + + let r = resp_of( + json!({}), + json!({"responses":{"200":{"description":"ok","schema":{"type":"string"}}}}), + ); + assert!(r["content"].get("application/json").is_some()); + + let r = resp_of(json!({}), json!({"responses":{"200":{"description":"ok"}}})); + assert!(r.get("content").is_none()); + } + + #[test] + fn response_headers_and_examples() { + let r = resp_of( + json!({}), + json!({"responses":{"200":{"description":"ok","schema":{"type":"object"}, + "headers":{"X-Rate":{"type":"integer","description":"limit"}}, + "examples":{"application/json":{"a":1}}}}}), + ); + assert_eq!( + r["headers"]["X-Rate"], + json!({"description":"limit","schema":{"type":"integer"}}) + ); + assert_eq!(r["content"]["application/json"]["example"], json!({"a":1})); + assert!(r.get("examples").is_none()); + } + + #[test] + fn response_refs_and_top_level_responses() { + let (out, _) = conv(json!({"swagger":"2.0","produces":["application/json"], + "responses":{"NotFound":{"description":"nf","schema":{"type":"string"}}}, + "paths":{"/p":{"get":{"responses":{"404":{"$ref":"#/responses/NotFound"}}}}}})); + assert_eq!( + out["paths"]["/p"]["get"]["responses"]["404"]["$ref"], + "#/components/responses/NotFound" + ); + assert!( + out["components"]["responses"]["NotFound"]["content"]["application/json"].is_object() + ); + assert!(out.get("produces").is_none()); + } + + #[test] + fn security_definitions() { + let (out, notes) = conv( + json!({"swagger":"2.0","security":[{"k":[]}],"securityDefinitions":{ + "b":{"type":"basic","description":"d"}, + "k":{"type":"apiKey","name":"X","in":"header"}, + "i":{"type":"oauth2","flow":"implicit","authorizationUrl":"https://a","scopes":{"r":"read"}}, + "p":{"type":"oauth2","flow":"password","tokenUrl":"https://t","scopes":{}}, + "a":{"type":"oauth2","flow":"application","tokenUrl":"https://t","scopes":{}}, + "c":{"type":"oauth2","flow":"accessCode","authorizationUrl":"https://a","tokenUrl":"https://t","scopes":{}}, + "x":{"type":"mystery"}}}), + ); + let s = &out["components"]["securitySchemes"]; + assert!(out.get("securityDefinitions").is_none()); + assert_eq!( + s["b"], + json!({"type":"http","scheme":"basic","description":"d"}) + ); + assert_eq!(s["k"], json!({"type":"apiKey","name":"X","in":"header"})); + assert_eq!( + s["i"], + json!({"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://a","scopes":{"r":"read"}}}}) + ); + assert_eq!(s["p"]["flows"]["password"]["tokenUrl"], "https://t"); + assert_eq!( + s["a"]["flows"]["clientCredentials"]["tokenUrl"], + "https://t" + ); + assert_eq!( + s["c"]["flows"]["authorizationCode"], + json!({"authorizationUrl":"https://a","tokenUrl":"https://t","scopes":{}}) + ); + assert_eq!(s["x"], json!({"type":"mystery"})); + assert!(notes + .iter() + .any(|n| n.contains("unknown security scheme type 'mystery'"))); + assert_eq!(out["security"], json!([{"k":[]}])); + } +} diff --git a/crates/openapi-aggregator-core/tests/fixtures/petstore2.json b/crates/openapi-aggregator-core/tests/fixtures/petstore2.json new file mode 100644 index 0000000..74a843e --- /dev/null +++ b/crates/openapi-aggregator-core/tests/fixtures/petstore2.json @@ -0,0 +1 @@ +{"swagger":"2.0","info":{"description":"This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters.","version":"1.0.9","title":"Swagger Petstore","termsOfService":"http://swagger.io/terms/","contact":{"email":"apiteam@swagger.io"},"license":{"name":"Apache 2.0","url":"http://www.apache.org/licenses/LICENSE-2.0.html"}},"host":"petstore.swagger.io","basePath":"/v2","tags":[{"name":"pet","description":"Everything about your Pets","externalDocs":{"description":"Find out more","url":"http://swagger.io"}},{"name":"store","description":"Access to Petstore orders"},{"name":"user","description":"Operations about user","externalDocs":{"description":"Find out more about our store","url":"http://swagger.io"}}],"schemes":["https","http"],"paths":{"/pet":{"post":{"tags":["pet"],"summary":"Add a new pet to the store","description":"","operationId":"addPet","consumes":["application/json","application/xml"],"produces":["application/json","application/xml"],"parameters":[{"in":"body","name":"body","description":"Pet object that needs to be added to the store","required":true,"schema":{"$ref":"#/definitions/Pet"}}],"security":[{"petstore_auth":["write:pets","read:pets"]}],"responses":{"405":{"description":"Invalid input"}}},"put":{"tags":["pet"],"summary":"Update an existing pet","description":"","operationId":"updatePet","consumes":["application/json","application/xml"],"produces":["application/json","application/xml"],"parameters":[{"in":"body","name":"body","description":"Pet object that needs to be added to the store","required":true,"schema":{"$ref":"#/definitions/Pet"}}],"security":[{"petstore_auth":["write:pets","read:pets"]}],"responses":{"400":{"description":"Invalid ID supplied"},"404":{"description":"Pet not found"},"405":{"description":"Validation exception"}}}},"/pet/findByStatus":{"get":{"tags":["pet"],"summary":"Finds Pets by status","description":"Multiple status values can be provided with comma separated strings","operationId":"findPetsByStatus","produces":["application/json","application/xml"],"parameters":[{"name":"status","in":"query","description":"Status values that need to be considered for filter","required":true,"type":"array","items":{"type":"string","enum":["available","pending","sold"],"default":"available"},"collectionFormat":"multi"}],"security":[{"petstore_auth":["write:pets","read:pets"]}],"responses":{"200":{"description":"successful operation","schema":{"type":"array","items":{"$ref":"#/definitions/Pet"}}},"400":{"description":"Invalid status value"}}}},"/pet/findByTags":{"get":{"tags":["pet"],"summary":"Finds Pets by tags","description":"Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.","operationId":"findPetsByTags","produces":["application/json","application/xml"],"parameters":[{"name":"tags","in":"query","description":"Tags to filter by","required":true,"type":"array","items":{"type":"string"},"collectionFormat":"multi"}],"security":[{"petstore_auth":["write:pets","read:pets"]}],"deprecated":true,"responses":{"200":{"description":"successful operation","schema":{"type":"array","items":{"$ref":"#/definitions/Pet"}}},"400":{"description":"Invalid tag value"}}}},"/pet/{petId}":{"get":{"tags":["pet"],"summary":"Find pet by ID","description":"Returns a single pet","operationId":"getPetById","produces":["application/json","application/xml"],"parameters":[{"name":"petId","in":"path","description":"ID of pet to return","required":true,"type":"integer","format":"int64"}],"security":[{"api_key":[]}],"responses":{"200":{"description":"successful operation","schema":{"$ref":"#/definitions/Pet"}},"400":{"description":"Invalid ID supplied"},"404":{"description":"Pet not found"}}},"post":{"tags":["pet"],"summary":"Updates a pet in the store with form data","description":"","operationId":"updatePetWithForm","consumes":["application/x-www-form-urlencoded"],"produces":["application/json","application/xml"],"parameters":[{"name":"petId","in":"path","description":"ID of pet that needs to be updated","required":true,"type":"integer","format":"int64"},{"name":"name","in":"formData","description":"Updated name of the pet","required":false,"type":"string"},{"name":"status","in":"formData","description":"Updated status of the pet","required":false,"type":"string"}],"security":[{"petstore_auth":["write:pets","read:pets"]}],"responses":{"405":{"description":"Invalid input"}}},"delete":{"tags":["pet"],"summary":"Deletes a pet","description":"","operationId":"deletePet","produces":["application/json","application/xml"],"parameters":[{"name":"api_key","in":"header","required":false,"type":"string"},{"name":"petId","in":"path","description":"Pet id to delete","required":true,"type":"integer","format":"int64"}],"security":[{"petstore_auth":["write:pets","read:pets"]}],"responses":{"400":{"description":"Invalid ID supplied"},"404":{"description":"Pet not found"}}}},"/pet/{petId}/uploadImage":{"post":{"tags":["pet"],"summary":"uploads an image","description":"","operationId":"uploadFile","consumes":["multipart/form-data"],"produces":["application/json"],"parameters":[{"name":"petId","in":"path","description":"ID of pet to update","required":true,"type":"integer","format":"int64"},{"name":"additionalMetadata","in":"formData","description":"Additional data to pass to server","required":false,"type":"string"},{"name":"file","in":"formData","description":"file to upload","required":false,"type":"file"}],"security":[{"petstore_auth":["write:pets","read:pets"]}],"responses":{"200":{"description":"successful operation","schema":{"$ref":"#/definitions/ApiResponse"}}}}},"/store/inventory":{"get":{"tags":["store"],"summary":"Returns pet inventories by status","description":"Returns a map of status codes to quantities","operationId":"getInventory","produces":["application/json"],"parameters":[],"security":[{"api_key":[]}],"responses":{"200":{"description":"successful operation","schema":{"type":"object","additionalProperties":{"type":"integer","format":"int32"}}}}}},"/store/order/{orderId}":{"get":{"tags":["store"],"summary":"Find purchase order by ID","description":"For valid response try integer IDs with value >= 1 and <= 10. Other values will generated exceptions","operationId":"getOrderById","produces":["application/json","application/xml"],"parameters":[{"name":"orderId","in":"path","description":"ID of pet that needs to be fetched","required":true,"type":"integer","maximum":10,"minimum":1,"format":"int64"}],"responses":{"200":{"description":"successful operation","schema":{"$ref":"#/definitions/Order"}},"400":{"description":"Invalid ID supplied"},"404":{"description":"Order not found"}}},"delete":{"tags":["store"],"summary":"Delete purchase order by ID","description":"For valid response try integer IDs with positive integer value. Negative or non-integer values will generate API errors","operationId":"deleteOrder","produces":["application/json","application/xml"],"parameters":[{"name":"orderId","in":"path","description":"ID of the order that needs to be deleted","required":true,"type":"integer","minimum":1,"format":"int64"}],"responses":{"400":{"description":"Invalid ID supplied"},"404":{"description":"Order not found"}}}},"/store/order":{"post":{"tags":["store"],"summary":"Place an order for a pet","description":"","operationId":"placeOrder","consumes":["application/json"],"produces":["application/json","application/xml"],"parameters":[{"in":"body","name":"body","description":"order placed for purchasing the pet","required":true,"schema":{"$ref":"#/definitions/Order"}}],"responses":{"200":{"description":"successful operation","schema":{"$ref":"#/definitions/Order"}},"400":{"description":"Invalid Order"}}}},"/user":{"post":{"tags":["user"],"summary":"Create user","description":"This can only be done by the logged in user.","operationId":"createUser","consumes":["application/json"],"produces":["application/json","application/xml"],"parameters":[{"in":"body","name":"body","description":"Created user object","required":true,"schema":{"$ref":"#/definitions/User"}}],"responses":{"default":{"description":"successful operation"}}}},"/user/logout":{"get":{"tags":["user"],"summary":"Logs out current logged in user session","description":"","operationId":"logoutUser","produces":["application/json","application/xml"],"parameters":[],"responses":{"default":{"description":"successful operation"}}}},"/user/createWithArray":{"post":{"tags":["user"],"summary":"Creates list of users with given input array","description":"","operationId":"createUsersWithArrayInput","consumes":["application/json"],"produces":["application/json","application/xml"],"parameters":[{"in":"body","name":"body","description":"List of user object","required":true,"schema":{"type":"array","items":{"$ref":"#/definitions/User"}}}],"responses":{"default":{"description":"successful operation"}}}},"/user/createWithList":{"post":{"tags":["user"],"summary":"Creates list of users with given input array","description":"","operationId":"createUsersWithListInput","consumes":["application/json"],"produces":["application/json","application/xml"],"parameters":[{"in":"body","name":"body","description":"List of user object","required":true,"schema":{"type":"array","items":{"$ref":"#/definitions/User"}}}],"responses":{"default":{"description":"successful operation"}}}},"/user/{username}":{"get":{"tags":["user"],"summary":"Get user by user name","description":"","operationId":"getUserByName","produces":["application/json","application/xml"],"parameters":[{"name":"username","in":"path","description":"The name that needs to be fetched. Use user1 for testing. ","required":true,"type":"string"}],"responses":{"200":{"description":"successful operation","schema":{"$ref":"#/definitions/User"}},"400":{"description":"Invalid username supplied"},"404":{"description":"User not found"}}},"put":{"tags":["user"],"summary":"Updated user","description":"This can only be done by the logged in user.","operationId":"updateUser","consumes":["application/json"],"produces":["application/json","application/xml"],"parameters":[{"name":"username","in":"path","description":"name that need to be updated","required":true,"type":"string"},{"in":"body","name":"body","description":"Updated user object","required":true,"schema":{"$ref":"#/definitions/User"}}],"responses":{"400":{"description":"Invalid user supplied"},"404":{"description":"User not found"}}},"delete":{"tags":["user"],"summary":"Delete user","description":"This can only be done by the logged in user.","operationId":"deleteUser","produces":["application/json","application/xml"],"parameters":[{"name":"username","in":"path","description":"The name that needs to be deleted","required":true,"type":"string"}],"responses":{"400":{"description":"Invalid username supplied"},"404":{"description":"User not found"}}}},"/user/login":{"get":{"tags":["user"],"summary":"Logs user into the system","description":"","operationId":"loginUser","produces":["application/json","application/xml"],"parameters":[{"name":"username","in":"query","description":"The user name for login","required":true,"type":"string"},{"name":"password","in":"query","description":"The password for login in clear text","required":true,"type":"string"}],"responses":{"200":{"description":"successful operation","headers":{"X-Expires-After":{"type":"string","format":"date-time","description":"date in UTC when token expires"},"X-Rate-Limit":{"type":"integer","format":"int32","description":"calls per hour allowed by the user"}},"schema":{"type":"string"}},"400":{"description":"Invalid username/password supplied"}}}}},"securityDefinitions":{"api_key":{"type":"apiKey","name":"api_key","in":"header"},"petstore_auth":{"type":"oauth2","authorizationUrl":"https://petstore.swagger.io/oauth/authorize","flow":"implicit","scopes":{"read:pets":"read your pets","write:pets":"modify pets in your account"}}},"definitions":{"Category":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"}},"xml":{"name":"Category"}},"Pet":{"type":"object","required":["name","photoUrls"],"properties":{"id":{"type":"integer","format":"int64"},"category":{"$ref":"#/definitions/Category"},"name":{"type":"string","example":"doggie"},"photoUrls":{"type":"array","xml":{"wrapped":true},"items":{"type":"string","xml":{"name":"photoUrl"}}},"tags":{"type":"array","xml":{"wrapped":true},"items":{"xml":{"name":"tag"},"$ref":"#/definitions/Tag"}},"status":{"type":"string","description":"pet status in the store","enum":["available","pending","sold"]}},"xml":{"name":"Pet"}},"Tag":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"}},"xml":{"name":"Tag"}},"ApiResponse":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"type":{"type":"string"},"message":{"type":"string"}}},"Order":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"petId":{"type":"integer","format":"int64"},"quantity":{"type":"integer","format":"int32"},"shipDate":{"type":"string","format":"date-time"},"status":{"type":"string","description":"Order Status","enum":["placed","approved","delivered"]},"complete":{"type":"boolean"}},"xml":{"name":"Order"}},"User":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"username":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"password":{"type":"string"},"phone":{"type":"string"},"userStatus":{"type":"integer","format":"int32","description":"User Status"}},"xml":{"name":"User"}}},"externalDocs":{"description":"Find out more about Swagger","url":"http://swagger.io"}} \ No newline at end of file diff --git a/crates/openapi-aggregator-core/tests/swagger2_petstore.rs b/crates/openapi-aggregator-core/tests/swagger2_petstore.rs new file mode 100644 index 0000000..d206517 --- /dev/null +++ b/crates/openapi-aggregator-core/tests/swagger2_petstore.rs @@ -0,0 +1,41 @@ +use openapi_aggregator_core::swagger2::convert; +use serde_json::Value; + +fn contains_str(value: &Value, needle: &str) -> bool { + match value { + Value::String(s) => s.contains(needle), + Value::Array(a) => a.iter().any(|v| contains_str(v, needle)), + Value::Object(m) => m.values().any(|v| contains_str(v, needle)), + _ => false, + } +} + +#[test] +fn petstore2_converts_to_valid_shape() { + let input: Value = serde_json::from_str(include_str!("fixtures/petstore2.json")).unwrap(); + let (out, notes) = convert(input); + + assert_eq!(out["openapi"], "3.0.3"); + assert!(out.get("swagger").is_none() && out.get("definitions").is_none()); + assert!(!notes.is_empty()); + + let pet_id = out["paths"]["/pet/{petId}"]["get"]["parameters"] + .as_array() + .unwrap() + .iter() + .find(|p| p["name"] == "petId") + .unwrap(); + assert_eq!(pet_id["schema"]["type"], "integer"); + + let content = &out["paths"]["/pet"]["post"]["requestBody"]["content"]; + assert!(content["application/json"].is_object() && content["application/xml"].is_object()); + + assert!(out["components"]["securitySchemes"]["petstore_auth"]["flows"]["implicit"].is_object()); + + let upload = &out["paths"]["/pet/{petId}/uploadImage"]["post"]["requestBody"]["content"] + ["multipart/form-data"]["schema"]["properties"]; + assert_eq!(upload["file"]["format"], "binary"); + + assert!(!contains_str(&out, "#/definitions/")); + assert!(!contains_str(&out, "#/parameters/") && !contains_str(&out, "#/responses/")); +} diff --git a/crates/openapi-aggregator-wasm/src/lib.rs b/crates/openapi-aggregator-wasm/src/lib.rs index 72608a3..4df4276 100644 --- a/crates/openapi-aggregator-wasm/src/lib.rs +++ b/crates/openapi-aggregator-wasm/src/lib.rs @@ -4,7 +4,7 @@ use std::collections::BTreeMap; use openapi_aggregator_core::{ - merge_specs_with_report, prepare_source, Config, Error, OutputFormat, Source, + merge_specs_with_report, prepare_source_with_notes, Config, Error, OutputFormat, Source, }; use serde::Serialize; use wasm_bindgen::prelude::*; @@ -81,20 +81,20 @@ pub fn aggregate_contents(yaml: &str, contents: Vec) -> Result format!("source '{}': {e}", source.display_name()), - other => other.to_string(), - })?; - Ok((name, source.tag_prefix(), spec)) - }) - .collect::, String>>()?; + let mut notes = Vec::new(); + let mut specs = Vec::new(); + for (source, content) in config.sources.iter().zip(&contents) { + let prepared = prepare_source_with_notes(content, source).map_err(|e| match e { + Error::Parse(_) => format!("source '{}': {e}", source.display_name()), + other => other.to_string(), + })?; + notes.extend(prepared.notes); + specs.push((prepared.name, source.tag_prefix(), prepared.spec)); + } - let report = merge_specs_with_report(specs, &config.merge).map_err(|e| e.to_string())?; + let mut report = merge_specs_with_report(specs, &config.merge).map_err(|e| e.to_string())?; + notes.append(&mut report.warnings); + report.warnings = notes; let text = match config.output.format { OutputFormat::Yaml => serde_yaml::to_string(&report.spec).map_err(|e| e.to_string())?, OutputFormat::Json => { @@ -199,4 +199,22 @@ mod tests { let err = aggregate_contents("sources:\n - path: pets.yaml\n", vec![]).unwrap_err(); assert!(err.contains("expected 1"), "{err}"); } + + #[test] + fn swagger2_sources_are_converted_with_a_warning() { + let legacy = "swagger: '2.0'\ninfo: {title: Legacy, version: '1'}\npaths:\n /legacy:\n get:\n responses:\n '200': {description: ok}\n"; + let out = aggregate_contents( + "sources:\n - name: legacy\n path: legacy.yaml\n - path: pets.yaml\n", + vec![legacy.into(), PETS.into()], + ) + .unwrap(); + assert!(out.text.contains("/legacy:") && out.text.contains("/pets:")); + assert!( + out.warnings + .iter() + .any(|w| w.contains("source 'legacy': converted from Swagger 2.0")), + "{:?}", + out.warnings + ); + } } diff --git a/crates/openapi-aggregator/src/lib.rs b/crates/openapi-aggregator/src/lib.rs index 617f3ab..ee677a3 100644 --- a/crates/openapi-aggregator/src/lib.rs +++ b/crates/openapi-aggregator/src/lib.rs @@ -11,9 +11,9 @@ pub mod source; pub use error::Error; pub use openapi_aggregator_core::{ - config, merge, merge_specs, merge_specs_with_report, parse_content, prepare_source, Config, - ConflictStrategy, InfoOverride, MergeConfig, MergeReport, OutputConfig, OutputFormat, - ServerEntry, Source, TagEntry, TagPrefixStrategy, + config, merge, merge_specs, merge_specs_with_report, parse_content, prepare_source, + prepare_source_with_notes, Config, ConflictStrategy, InfoOverride, MergeConfig, MergeReport, + OutputConfig, OutputFormat, PreparedSource, ServerEntry, Source, TagEntry, TagPrefixStrategy, }; pub use source::load_source; @@ -39,13 +39,23 @@ pub async fn aggregate_with_report(config: &Config) -> Result((name, src.tag_prefix(), spec)) + let prepared = try_join_all(config.sources.iter().map(|src| async { + let prepared = load_source_with_client(src, &client).await?; + Ok::<_, Error>(prepared) })) .await?; - Ok(merge_specs_with_report(specs, &config.merge)?) + let mut notes = Vec::new(); + let mut specs = Vec::new(); + for (src, prepared) in config.sources.iter().zip(prepared) { + notes.extend(prepared.notes); + specs.push((prepared.name, src.tag_prefix(), prepared.spec)); + } + + let mut report = merge_specs_with_report(specs, &config.merge)?; + notes.append(&mut report.warnings); + report.warnings = notes; + Ok(report) } /// Read a config file and resolve relative source paths against its directory. diff --git a/crates/openapi-aggregator/src/source.rs b/crates/openapi-aggregator/src/source.rs index 2cfe7fa..c42501a 100644 --- a/crates/openapi-aggregator/src/source.rs +++ b/crates/openapi-aggregator/src/source.rs @@ -1,12 +1,15 @@ use serde_json::Value; use std::time::Duration; -use openapi_aggregator_core::{prepare_source, Error as CoreError, Source}; +use openapi_aggregator_core::{ + prepare_source_with_notes, Error as CoreError, PreparedSource, Source, +}; use crate::error::Error; pub async fn load_source(source: &Source) -> Result<(String, Value), Error> { - load_source_with_client(source, &http_client()?).await + let prepared = load_source_with_client(source, &http_client()?).await?; + Ok((prepared.name, prepared.spec)) } pub(crate) fn http_client() -> Result { @@ -23,7 +26,7 @@ pub(crate) fn http_client() -> Result { pub(crate) async fn load_source_with_client( source: &Source, client: &reqwest::Client, -) -> Result<(String, Value), Error> { +) -> Result { let content = match source { Source::File { path, .. } => { tokio::fs::read_to_string(path) @@ -55,7 +58,7 @@ pub(crate) async fn load_source_with_client( } }; - Ok(prepare_source(&content, source)?) + Ok(prepare_source_with_notes(&content, source)?) } /// Replace `${NAME}` placeholders with environment variables. diff --git a/crates/openapi-aggregator/tests/fixtures/swagger2.yaml b/crates/openapi-aggregator/tests/fixtures/swagger2.yaml new file mode 100644 index 0000000..28f1efb --- /dev/null +++ b/crates/openapi-aggregator/tests/fixtures/swagger2.yaml @@ -0,0 +1,29 @@ +swagger: "2.0" +info: + title: Legacy Pets + version: "1.0" +host: legacy.example.com +basePath: /v1 +schemes: [https] +consumes: [application/json] +produces: [application/json] +paths: + /legacy-pets: + post: + parameters: + - in: body + name: pet + required: true + schema: + $ref: "#/definitions/Pet" + responses: + "201": + description: created + schema: + $ref: "#/definitions/Pet" +definitions: + Pet: + type: object + properties: + name: + type: string diff --git a/crates/openapi-aggregator/tests/integration_test.rs b/crates/openapi-aggregator/tests/integration_test.rs index 9ec2add..176ac92 100644 --- a/crates/openapi-aggregator/tests/integration_test.rs +++ b/crates/openapi-aggregator/tests/integration_test.rs @@ -441,3 +441,58 @@ async fn http_errors_do_not_leak_expanded_env_secrets() { "{message}" ); } + +fn collect_refs(value: &serde_json::Value, out: &mut Vec) { + match value { + serde_json::Value::Object(map) => { + for (k, v) in map { + match v { + serde_json::Value::String(s) if k == "$ref" => out.push(s.clone()), + _ => collect_refs(v, out), + } + } + } + serde_json::Value::Array(items) => items.iter().for_each(|v| collect_refs(v, out)), + _ => {} + } +} + +#[tokio::test] +async fn swagger2_source_merges_with_openapi3_and_refs_resolve() { + let config = Config { + sources: vec![ + Source::File { + name: Some("petstore".into()), + path: fixtures().join("petstore.yaml"), + tag_prefix: None, + additional_blocks: None, + }, + Source::File { + name: Some("legacy".into()), + path: fixtures().join("swagger2.yaml"), + tag_prefix: None, + additional_blocks: None, + }, + ], + output: Default::default(), + merge: MergeConfig { + conflict_strategy: ConflictStrategy::Rename, + ..Default::default() + }, + }; + let report = aggregate_with_report(&config).await.unwrap(); + assert_eq!(report.spec["openapi"], "3.0.3"); + assert!(report.spec["paths"]["/legacy-pets"]["post"]["requestBody"].is_object()); + assert!(report + .warnings + .iter() + .any(|w| w.contains("source 'legacy': converted from Swagger 2.0"))); + + let mut refs = Vec::new(); + collect_refs(&report.spec, &mut refs); + assert!(!refs.is_empty()); + for r in refs { + let pointer = r.trim_start_matches('#'); + assert!(report.spec.pointer(pointer).is_some(), "dangling $ref {r}"); + } +} diff --git a/web/src/examples.ts b/web/src/examples.ts index 0682965..1f6e708 100644 --- a/web/src/examples.ts +++ b/web/src/examples.ts @@ -149,6 +149,37 @@ components: title: { type: string } `; +const LEGACY_SWAGGER2 = `swagger: '2.0' +info: + title: Legacy Pets + version: 1.0.0 +host: legacy.example.com +basePath: /v1 +schemes: [https] +consumes: [application/json] +produces: [application/json] +paths: + /legacy-pets: + post: + summary: Add a pet + parameters: + - in: body + name: pet + required: true + schema: + $ref: '#/definitions/LegacyPet' + responses: + '201': + description: Created + schema: + $ref: '#/definitions/LegacyPet' +definitions: + LegacyPet: + type: object + properties: + name: { type: string } +`; + export const EXAMPLES: Example[] = [ { id: 'rename', @@ -246,6 +277,22 @@ output: `, files: [{ name: 'specs/users.yaml', content: USERS }], }, + { + id: 'swagger2', + title: 'Swagger 2.0 + OpenAPI 3', + config: `# A Swagger 2.0 source is converted to OpenAPI 3.0.3 automatically. +# Anything that had to be approximated is reported as a warning. +sources: + - name: legacy + path: ./specs/legacy.yaml + - name: users + path: ./specs/users.yaml +`, + files: [ + { name: 'specs/legacy.yaml', content: LEGACY_SWAGGER2 }, + { name: 'specs/users.yaml', content: USERS }, + ], + }, { id: 'remote', title: 'Remote URL + local file', diff --git a/web/tests/examples.test.ts b/web/tests/examples.test.ts index dd3510c..d22dff4 100644 --- a/web/tests/examples.test.ts +++ b/web/tests/examples.test.ts @@ -25,7 +25,8 @@ describe('examples', () => { }); const usesNetwork = parseConfigSafe(example.config).some((s) => s.kind === 'url'); - it.skipIf(usesNetwork)(`${example.id}: merges without errors or warnings`, async () => { + const expectsWarnings = example.id === 'swagger2'; + it.skipIf(usesNetwork || expectsWarnings)(`${example.id}: merges without errors or warnings`, async () => { const summary = parseConfig(example.config); const { contents, problems } = await resolveSources(summary.sources, example.files, noNetwork); expect(problems).toEqual([]); @@ -44,6 +45,17 @@ describe('examples', () => { expect(text).toContain("'#/components/schemas/catalog_Item'"); }); + it('swagger2 example converts the legacy spec and says so', async () => { + const ex = findExample('swagger2'); + expect(ex.id).toBe('swagger2'); + const { contents, problems } = await resolveSources(parseConfig(ex.config).sources, ex.files, noNetwork); + expect(problems).toEqual([]); + const out = aggregate(ex.config, contents!); + expect(out.text).toContain('openapi: 3.0.3'); + expect(out.text).toContain('requestBody:'); + expect(out.warnings.some((w) => w.includes('converted from Swagger 2.0'))).toBe(true); + }); + 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); diff --git a/web/tests/pipeline.test.ts b/web/tests/pipeline.test.ts index 6e40f28..a973af2 100644 --- a/web/tests/pipeline.test.ts +++ b/web/tests/pipeline.test.ts @@ -26,16 +26,27 @@ describe('runPipeline', () => { expect(result.problems[0].line).toBeGreaterThan(0); }); - it('names a Swagger 2.0 source and says only 3.x is supported', async () => { + it('converts a Swagger 2.0 source and reports a warning', async () => { const result = await runPipeline( 'sources:\n - name: legacy\n path: old.yaml\n', [{ name: 'old.yaml', content: "swagger: '2.0'\ninfo: {title: Old, version: '1'}\npaths: {}\n" }], deps(), ); + expect(result.text).toContain('openapi: 3.0.3'); + expect(result.problems).toEqual([ + expect.objectContaining({ level: 'warning', kind: 'merge', message: expect.stringContaining("source 'legacy': converted from Swagger 2.0") }), + ]); + }); + + it('rejects Swagger 1.x sources by name', async () => { + const result = await runPipeline( + 'sources:\n - name: ancient\n path: old.yaml\n', + [{ name: 'old.yaml', content: "swagger: '1.2'\ninfo: {title: Old, version: '1'}\n" }], + deps(), + ); expect(result.text).toBeNull(); - expect(result.problems[0]).toMatchObject({ kind: 'merge' }); - expect(result.problems[0].message).toMatch(/legacy/); - expect(result.problems[0].message).toMatch(/only OpenAPI 3\.x/); + expect(result.problems[0].message).toMatch(/ancient/); + expect(result.problems[0].message).toMatch(/Swagger 1\.x/); }); it('turns merge warnings into warning problems while keeping output', async () => {