Diff

Public API for comparing OpenAPI documents.

APIDiff

Bases: BaseModel

Structured differences between two OpenAPI documents.

Attributes:

Name	Type	Description
operation_changes	list[OperationChange]	Added, removed, and modified operations.
schema_changes	list[SchemaChange]	Added, removed, and modified schemas.

ChangeType

Bases: StrEnum

Type of change between the base and head OpenAPI documents.

Attributes:

Name	Type	Description
ADDED		An item exists only in the head document.
REMOVED		An item exists only in the base document.
MODIFIED		An item exists in both documents but has changed.

FieldChange

Bases: BaseModel

Change to a field on an OpenAPI object.

Attributes:

Name	Type	Description
field	str	Name of the changed field.
old_value	Any	Value in the base document.
new_value	Any	Value in the head document.

OperationChange

Bases: BaseModel

Change to an OpenAPI operation.

Attributes:

Name	Type	Description
path	str	URL path of the operation.
method	str	Lowercase HTTP method of the operation.
change_type	ChangeType	Type of change to the operation.
parameter_changes	list[ParameterChange]	Changes to the operation's parameters.
request_body_change	RequestBodyChange | None	Change to the request body, if any.
response_changes	list[ResponseChange]	Changes to the operation's responses.
affected_schema_changes	list[str]	Names of changed schemas used by the operation.

ParameterChange

Bases: BaseModel

Change to an operation parameter.

Attributes:

Name	Type	Description
name	str	Parameter name.
location	str	Parameter location, such as path or query.
change_type	ChangeType	Type of change to the parameter.
field_changes	list[FieldChange]	Changes to fields on the parameter.

RequestBodyChange

Bases: BaseModel

Change to an operation request body.

Attributes:

Name	Type	Description
change_type	ChangeType	Type of change to the request body.
field_changes	list[FieldChange]	Changes to fields on the request body.

ResponseChange

Bases: BaseModel

Change to an operation response.

Attributes:

Name	Type	Description
status_code	str	HTTP response status code or OpenAPI response key.
change_type	ChangeType	Type of change to the response.
field_changes	list[FieldChange]	Changes to fields on the response.

SchemaChange

Bases: BaseModel

Change to an OpenAPI schema.

Attributes:

Name	Type	Description
name	str	Schema name.
change_type	ChangeType	Type of change to the schema.
property_changes	list[SchemaPropertyChange]	Changes to properties on the schema.

SchemaPropertyChange

Bases: BaseModel

Change to a schema property.

Attributes:

Name	Type	Description
name	str	Property name.
change_type	ChangeType	Type of change to the property.
field_changes	list[FieldChange]	Changes to fields on the property.

compare(base, head)

Compare two OpenAPI documents.

Parameters:

Name	Type	Description	Default
base	OpenAPIParser	Parser containing the original OpenAPI document.	required
head	OpenAPIParser	Parser containing the updated OpenAPI document.	required

Returns:

Type	Description
APIDiff	The structured changes needed to move from base to head.

to_json(diff)

Serialize an API diff as JSON.

Parameters:

Name	Type	Description	Default
diff	APIDiff	Structured API diff to serialize.	required

Returns:

Type	Description
str	An indented JSON representation of the diff.

to_markdown(diff, *, heading_level=1)

Render an API diff as human-readable Markdown.

Parameters:

Name	Type	Description	Default
diff	APIDiff	Structured API diff to render.	required
heading_level	int	Heading level for the Operations and Schemas sections. Values outside the range 1 through 6 are clamped to that range.	1

Returns:

Type	Description
str	A Markdown representation of the diff, or an empty string when the
str	documents have no differences.