Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

49 changes: 49 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,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
- **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
Expand Down Expand Up @@ -61,6 +62,9 @@ openapi-aggregator -c my-config.yaml -o merged.yaml
# Output as JSON
openapi-aggregator -c my-config.yaml -f json

# Validate the merged spec and verify that merged.yaml is up to date (writes nothing)
openapi-aggregator -c my-config.yaml -o merged.yaml --check

# Print help
openapi-aggregator --help
```
Expand Down Expand Up @@ -140,6 +144,51 @@ A source may point at other files or URLs (`$ref: ./schemas/pet.yaml#/Pet`, `$re
- **Limit:** at most 100 external documents per source.
- **Playground:** referenced files are looked up in the workspace by name, so add each one under exactly the name the `$ref` resolves to (the error message tells you which). Remote refs follow the same "Allow fetching" rule as remote sources.

## Validation and CI

`--check` merges the sources, validates the result, and exits non-zero on problems, so it can gate a CI job. It never writes anything and prints nothing to stdout; findings go to stderr.

```sh
openapi-aggregator --check -c openapi-aggregator.yaml -o openapi.yaml
```

- **Validation** always runs. It checks what an aggregation can break (it is not a full OpenAPI schema validation).
- **Output comparison** runs when `-o` is given: the file is parsed and compared with the freshly merged spec *as data*, so formatting, YAML vs JSON and key order never count as a difference. On a mismatch a unified diff is printed. A missing or unparseable file counts as out of date.
- **`--deny-warnings`** also fails on warnings (merge warnings, Swagger 2.0 conversion notes and validation warnings).

| Exit code | Meaning |
|-----------|---------|
| `0` | Passed |
| `1` | Validation errors, denied warnings, or the merge/config itself failed (if the file is also out of date, the diff is still printed) |
| `2` | The output file is missing or out of date. Note that command-line usage errors also exit `2`. |

Findings look like `error[dangling-ref] /paths/~1pets/get/...: $ref '#/components/schemas/Ghost' does not resolve`, where the location is a JSON pointer into the merged spec.

| Code | Severity | Meaning |
|------|----------|---------|
| `invalid-openapi-version` | error | `openapi` is missing or not a 3.x version |
| `missing-field` | error | `info`, `info.title`, `info.version` missing; `paths` missing (3.0), or none of `paths`/`webhooks`/`components` (3.1+) |
| `dangling-ref` | error | an internal `$ref` that does not resolve |
| `external-ref` | error | a `$ref` outside the document that was not bundled |
| `duplicate-operation-id` | error | the same `operationId` on two operations |
| `missing-responses` | error | an operation without `responses` |
| `undeclared-path-param` | error | `{name}` in a path with no matching `in: path` parameter |
| `unused-path-param` | warning | a path parameter that is not in the path |
| `duplicate-parameter` | error | the same `name` and `in` declared twice |
| `ambiguous-paths` | error | two paths that differ only in placeholder names |
| `unknown-security-scheme` | error | a `security` requirement naming an undefined scheme |
| `undeclared-tag` | warning | an operation tag missing from the top-level `tags` (only checked when `tags` is non-empty) |
| `invalid-component-name` | error | a component name outside `[a-zA-Z0-9._-]+` |

Example GitHub Actions step that keeps a committed spec in sync:

```yaml
- name: Check the aggregated spec
run: openapi-aggregator --check --deny-warnings -c openapi-aggregator.yaml -o openapi.yaml
```

The same validator is available as `openapi_aggregator::validate(&spec)`, and the playground shows its findings in the problems panel.

## Library Usage

```rust
Expand Down
35 changes: 29 additions & 6 deletions crates/openapi-aggregator-core/src/bundle.rs
Original file line number Diff line number Diff line change
Expand Up @@ -149,23 +149,46 @@ const DATA_KEYS: [&str; 4] = ["example", "default", "enum", "value"];

/// Visit every `$ref` string, skipping example/default/enum data.
pub(crate) fn walk_refs(value: &Value, f: &mut dyn FnMut(&str)) {
walk(value, false, f);
walk_refs_at(value, &mut |_, reference| f(reference));
}

fn walk(value: &Value, names: bool, f: &mut dyn FnMut(&str)) {
/// Like [`walk_refs`], also giving the JSON pointer of the object that holds each `$ref`.
pub(crate) fn walk_refs_at(value: &Value, f: &mut dyn FnMut(&str, &str)) {
walk(value, false, &mut String::new(), f);
}

fn walk(value: &Value, names: bool, pointer: &mut String, f: &mut dyn FnMut(&str, &str)) {
match value {
Value::Object(map) => {
for (key, child) in map {
if !names && DATA_KEYS.contains(&key.as_str()) {
continue;
}
match child {
Value::String(target) if !names && key == "$ref" => f(target),
_ => walk(child, !names && NAME_MAPS.contains(&key.as_str()), f),
Value::String(target) if !names && key == "$ref" => f(pointer, target),
_ => {
let len = pointer.len();
pointer.push('/');
pointer.push_str(&crate::validate::pointer_escape(key));
walk(
child,
!names && NAME_MAPS.contains(&key.as_str()),
pointer,
f,
);
pointer.truncate(len);
}
}
}
}
Value::Array(items) => items.iter().for_each(|item| walk(item, false, f)),
Value::Array(items) => {
for (index, item) in items.iter().enumerate() {
let len = pointer.len();
pointer.push_str(&format!("/{index}"));
walk(item, false, pointer, f);
pointer.truncate(len);
}
}
_ => {}
}
}
Expand Down Expand Up @@ -308,7 +331,7 @@ fn sanitize_name(name: &str) -> String {
}
}

fn lookup<'v>(document: &'v Value, segments: &[String]) -> Option<&'v Value> {
pub(crate) fn lookup<'v>(document: &'v Value, segments: &[String]) -> Option<&'v Value> {
let mut current = document;
for segment in segments {
current = match current {
Expand Down
2 changes: 2 additions & 0 deletions crates/openapi-aggregator-core/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@ pub mod error;
pub mod merge;
pub mod prepare;
pub mod swagger2;
pub mod validate;

pub use bundle::{
bundle, check_document_cap, is_url, missing_documents, resolve_location, MissingDocument,
Expand All @@ -55,3 +56,4 @@ pub use merge::{merge_specs, merge_specs_with_report, MergeReport};
pub use prepare::{
bundle_source, parse_content, prepare_source, prepare_source_with_notes, PreparedSource,
};
pub use validate::{validate, Finding, Severity};
2 changes: 1 addition & 1 deletion crates/openapi-aggregator-core/src/swagger2.rs
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ pub fn convert(spec: Value) -> (Value, Vec<String>) {
(out, notes)
}

const METHODS: [&str; 8] = [
pub(crate) const METHODS: [&str; 8] = [
"get", "put", "post", "delete", "options", "head", "patch", "trace",
];

Expand Down
Loading
Loading