Open adamw opened 3 months ago
What's the "user story" here? Is it something like:
?
This, or: develops an API, publishes it, and wants to ensure that anything that's changed doesn't break the published contract
https://github.com/softwaremill/sttp-apispec/pull/157 introduced SchemaComparator
to check compatibility between schemas. This is likely the most complex part of full OpenAPI validation. Schema comparator would be used:
Possible improvements to SchemaComparator
:
Schema
patterns and JSON Schema keywords (see https://github.com/softwaremill/sttp-apispec/pull/157 for more details on comparator's assumptions and limitations)format
values are compatible, or that some particular schema patterns are compatible in specific use cases. It may be worth to open SchemaComparator
's implementation to extensions which would allow the user to override parts of its logic, in order to fine-tune it to their needs and avoid false negatives.Further work needed to have a full OpenApi comparator:
OpenAPI
can be deserialized (it looks to me like all the decoders are already there, but I haven't tested them)OpenAPIComparator
similar to SchemaComparator
.
This requires comparing the following OpenAPI objects: MediaType
, Encoding
, RequestBody
, Responses
, Response
, Header
, Parameter
, Operation
, PathItem
, and ultimately OpenAPI
itself.content
is incompatible with server content
(see below for details)style
or explode
don't match between client and serverallowEmptyValue
is true
for client but false
for serverallowReserved
is true
for client but false
for servercontent
is incompatible with server content
(see below for details)default
)content
is incompatible with client response content
(see below for details)content
is incompatible with client header content
(see below for details)style
or explode
don't match between server and clientallowEmptyValue
is true
for server but false
for clientallowReserved
is true
for server but false
for clientCompatibility issues for content
comparison:
content
but not defined in reader's content
encoding
?Note: "writer" and "reader" correspond to:
Sometimes it might be desirable to verify if the endpoints match a given OpenAPI schema. To implement this, we would need to parse the schema (see https://github.com/softwaremill/sttp-apispec/issues/2 - although this is already partially done), and then invoke comparison of the two schemas (generated from endpoints & parsed), ignoring fields which do not matter (e.g. descriptions, or examples)