search

westfieldlabs / apivore

Tests your rails API against its Swagger description of end-points, models, and query parameters.
Apache License 2.0
213 stars 66 forks source link

Add support for swagger consistency checks #21

Closed mastfish closed 9 years ago

mastfish commented 9 years ago

Usage: 

apivore_check_consistency_with_swagger_at "example.com"

It will then then look at http://example.com/swagger.json, and check to make sure there are no inconsistencies.

hornc commented 9 years ago

Can you provide a definition of 'inconsistencies'? Is it just that the definitions blocks in the two swagger.jsons should match?

mastfish commented 9 years ago

Kind of. The supplied uri should return a superset of all definitions, and the service being tested cannot have definitions which disagree with that source of truth.

So for example, at "example.com/swagger.json", there might be definitions: product category

And at the service being tested, there might be a definition: category

This is fine, as long as the category documentation is the same in both swaggers.

leondewey commented 9 years ago

@mastfish so if I get this right you want to enforce via apivore that we use /swagger.json ?

mastfish commented 9 years ago

Consider 2 services - one of them has a definition for "422Error" that refers to "product", and one has a definition of "422Error" that refers to "deal".

Then consider a third service, "api.westfield.io", that's trying to create a consistent swagger doc from both. Clearly, there's a merge conflict here, one that requires one (or both) of those services to change their "422Error" definitions.

This is designed so that trying to publish a "422Error" that disagrees with "api.westfield.io"'s swagger definitions throws an error, using it as a canonical source of truth.

It's opt-in, so upgrading apivore won't cause surprise errors, and it targets definitions only, because testing revealed that paths (should) have only one source of truth, so there's no need to cross-check them.

chrisrbnelson commented 9 years ago

LGTM! Will be nice to bring all the definitions in line with each other.