Crate vimanam 

Parse OpenAPI specs, compare their contracts, and render focused Markdown context.

The default cli feature includes the binary. Depend on the core alone with vimanam = { version = "1.6", default-features = false }. Library routines never write to stdout/stderr: rendering accepts a writer, optional notices go to a caller callback, and parsing logs through log.

let old = vimanam::parse_openapi("immich-v1.105.1.json")?;
let new = vimanam::parse_openapi("immich-v1.106.0.json")?;
let old_sha = vimanam::diff::json::sha256_hex(&std::fs::read("immich-v1.105.1.json")?);
let new_sha = vimanam::diff::json::sha256_hex(&std::fs::read("immich-v1.106.0.json")?);
let diff = vimanam::diff::diff(&old, &new);
let document = vimanam::diff::json::to_json(&diff, None, &old_sha, &new_sha);
for change in &document.changes {
    println!("{} {:?} {:?}", change.id, change.kind, change.severity);
}

For hashes tied to exactly the bytes parsed, use parse_openapi_bytes. Select operations with DocConfig::operation_selector and schemas with DocConfig::schema_names or DocConfig::schema_fields, then call markdown::generate_markdown. See DocConfig::unfiltered for defaults.

Modules

contract

Format-neutral contract surfaces and adapter-classified change records.

diff

vimanam diff <OLD> <NEW>: compares two versions of a spec and reports what changed, classified as breaking, non-breaking or needing review.

gitrefs

Discover committed OpenAPI candidates and read spec bytes through Git on PATH.

markdown

Focused Markdown context from a parsed OpenAPI document.

selection

Diagnostics for the exact operation selector (--operation, --operation-id). The selection itself is applied as one more filter in the views (see OperationSelector::matches); this module reports selectors that matched nothing in the spec (an error) and selectors whose operations another filter removed (a warning).

Structs

ApiDocumentation

Intermediate representation for documentation generation

DocConfig

Configuration for documentation generation

Encoding

Serialization metadata for one media-type property.

Endpoint

An operation normalized across OpenAPI versions.

Example

A named example declaration or reference.

Header

Header description and schema.

MediaType

Schema, examples, and encoding for a media type.

OperationRef

One --operation value: an uppercased HTTP method and a path template that must equal Endpoint::path byte for byte.

OperationSelector

The exact-operation selection from --operation and --operation-id. An endpoint is selected when it matches any entry of either set (a union). IndexSet keeps the order the values were given, so the unmatched-selector error lists them deterministically.

Parameter

A parameter declaration, or a synthetic OAS3 request-body parameter.

Response

A response declaration with its schema and media types.

Schema

A source schema with property order and unknown metadata preserved.

Service

A tag-derived service used to group operations.

Enums

AdditionalProperties

Policy for extra properties of an object schema.

DetailLevel

Amount of information included in operation context.

GroupBy

Grouping strategy for Markdown operation context.

SortMethod

Operation ordering within a rendered group.

Functions

parse_openapi

Parses an OpenAPI 2.0/3.0 file (JSON or YAML) into the spec-version-agnostic ApiDocumentation intermediate representation. On deserialization failure, re-parses as generic JSON/YAML to produce a targeted error message.

parse_openapi_bytes

Parses an OpenAPI spec from already-read bytes. Callers that also hash the raw file (diff --format json derives file_sha256 from it) parse exactly the bytes they hashed, so the two can never refer to different contents. extension selects the parser (case-insensitively; anything that is not “yaml”/“yml” starts with the JSON parser). path is only used in warning messages and may be None for in-memory sources.