Three questions about documentation

[ozersenturk]

Hi there,

First of all, thanks for the nice work. I appreciate it.

I could not understand three points regarding the documentation. Maybe you can clarify.

1. Contracts and stubs are generated on the producer side via restdocs and wiremock. Meanwhile, a consumer can also write a contract on producers code base and deploy it to maven via skiptests option. The second one looks more consumer driven. My question is, why is there the first one? Why are we generating contracts in producer side? Shouldn't we always expect consumers to write their own contracts?

2. I see that currently only maven is supported as a mean of broker. Do you have any plans to have a separate broker service/application? Because consumers writing contracts (code) on producers side looks a bit problematic.

3. Do you have any benchmarks or usage comments regarding spring cloud contract vs pact?

Best regards.

Özer

[marcingrzejszczak]

Hi @ozersenturk.

Thanks for your questions! They are really valuable! Let me answer them one by one

QUESTION 1

Contracts and stubs are generated on the producer side via restdocs and wiremock.

You're mixing 2 things here. One approach is that the contracts lay with the producer. That way the producer OWNS the contracts. Thus as a consumer if we need to introduce a new endpoint etc. then we'll file a PR to the producer's code.

If you're using Restdocs then you're not really doing consumer driven contracts. It's more producer contracts cause it's the producer that writes the MVC tests and produces stubs out of it.

Meanwhile, a consumer can also write a contract on producers code base and deploy it to maven via skiptests option.

The consumer will write the contract to file a PR and will NOT upload the stubs to Nexus / Artifactory. The consumer will install them locally to play around with the API offline. Does it make sense?

The second one looks more consumer driven

IMO quite the contrary. When the producer writes the the tests the consumer can't really take part in this (other than pair programming or sth).

Why are we generating contracts in producer side? Shouldn't we always expect consumers to write their own contracts

Because contracts are expectations. Expectations of how the producer should work. Stubs that are deployed to Nexus / Artifactory are those that we (as consumers) can trust. That means that we need to check the contents of contracts against the producer. Cause the producer is the one that contains the API. What the consumer writes in the contract is sth like wishful thinking. That's why on the producer side from the contract we're generating producer tests and stubs. Once the tests pass we can upload the newest stubs and contracts for reuse.

QUESTION 2

I see that currently only maven is supported as a mean of broker. Do you have any plans to have a separate broker service/application? Because consumers writing contracts (code) on producers side looks a bit problematic.

As written in the docs https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html#_custom_stub_downloader in the upcoming release you'll be able to provide any way of downloading stubs. So basically what the API of SC-Contract requires is to provide the folder where the stubs reside. How you get them is up to you.

Currently we were not planning on writing any broker for this. But look at the answer to the next question...

QUESTION 3

Do you have any benchmarks or usage comments regarding spring cloud contract vs pact?

We don't have benchmarks but we have some arguments for using SC-Contract https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html#_why_use_spring_cloud_contract_verifier_and_not_x . Another thing is that we do support PACT as input! So you can use both Pact and Spring Cloud Contract https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html#_pact_converter . That means that you can also very easily write a Stub Downloader that will call Pact broker to download pact definitions and convert them into stubs.

Hopefully I've managed to answer your questions but feel free to ask more in any time :)

[ozersenturk]

Thank you very much indeed. That cleared lots of things :) And its nice to hear about Pact :) I will check the links...

One more question though...

The consumer files a PR. Inside this PR, there is the wishful contract. Then the producer implements this wishful contract, tests and documents it, finally another contract gets generated. Now, in the codebase there is the wishful contract plus the generated one. Did I get it wrong? Should the producer delete/reject the PR so only the generated one remains?

Best regards.

Özer

[marcingrzejszczak]

The consumer files a PR. Inside this PR, there is the wishful contract. Then the producer implements this wishful contract, tests and documents it, finally another contract gets generated. Now, in the codebase there is the wishful contract plus the generated one. Did I get it wrong? Should the producer delete/reject the PR so only the generated one remains?

You get it almost correct ;) The PR contains a wishful contract. The producer takes over the PR (remember that from the contract tests are generated). So the PR will not be built because the autogenerated tests will fail (for example due to missing endpoint). So the producer needs to write the missing implementation to make the tests pass. Now in the codebase we have the contract that the consumer filed in the PR. Once merged to master, the CI tool will build that project and generate a fat-jar of the application and stubs generated from the contract.

BTW 1

you can also use the approach with common repo with contracts https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html#_common_repo_with_contracts

BTW 2

have you seen the video where I explain the whole flow? https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html#_spring_cloud_contract_video

[ozersenturk]

Thank you very much for your help. I will watch the video now, although I am pretty clear :)