search

spec-first / connexion

Connexion is a modern Python web framework that makes spec-first and api-first development easy.
https://connexion.readthedocs.io/en/latest/
Apache License 2.0
4.47k stars 757 forks source link

MockResolver: support "x-amples" in definitions #336

Open elgalu opened 7 years ago

elgalu commented 7 years ago

Following #292 and #308 it would be also interesting to support the x-amples swagger extension which goes beyond response-only examples by allowing the explicit specification of request/response example pairs.

This supported extension could also be the foundation for future contract testing related features, this inter-microservices contract testing workflow could potentially look something like this:

(1) The Consumer sends a PR to the Provider's swagger.yaml by adding to the x-amples section the ones they are using and whose contract is important to be kept from an API consumer perspective

(2) The Provider accepts the PR as long as is consistent with the spec.

(2.1) Once accepted the Provider will include the validation of those x-amples during unit the tests, this means the Provider will setup the necessary test data to validate that is consistently able to fulfill and respect this contract, preventing breaking changes going without notice.

(2.2) When a breaking change is detected, the Provider should contact all the Consumers and request them to upgrade the x-amples that matches the new API and a proper transition to the new API can be negotiated without breaking them in production.

(2.3) Every time the Provider runs the unit contract tests it POST the results to a broker service (this doesn't exist yet) similar to a pact_broker but the difference is that we don't host the contracts there as we've just moved them to the swagger.yml x-amples section. This xamples_broker (to name it somehow) will act as a central point of confirmation for Consumers so they can be at peace that their contracts are actually being unit tested and not left to forgetfulness. This feature would be something like this

(3) With this x-amples support in place Consumers can now spin up a mock server out of the empowered swagger.yml file and have mocked dependencies out of the box, which takes us back to this feature request:)

hjacobs commented 7 years ago

@elgalu sounds like a plan :smirk:

Are you willing to work on a PR for this? Personally I think implementing #308 would be of more general use, i.e. should be done first.

elgalu commented 7 years ago

Working on this PR? not really.. for now just raised the issue to see what folks think:)

elgalu commented 7 years ago

Also (slightly) related https://github.com/pact-foundation/pact-specification/issues/28