Provide an editor which allows to define contracts in an easy/easier way

[ingogriebsch]

Some time ago we started to use Consumer Driven Contracts.

All the colleagues where keen to understand how it works because we got more and more problems to change the APIs in a robust way and especially to realize if we did some breaking change. After investigating a little bit we decided to use Spring Cloud Contract (not only because we are Spring fanboys).

So we integrated it into one of our services and did a first little story on it. We also agreed on having an API first meeting if we do a story which has the need to change/enhance an API. The one really nice thing we realized is, that the colleagues from both 'sides' (frontend and backend) started to discuss the API in far more detail.

But we also realized that the colleagues had problems to write down the contracts after the discussion. Another language and a DSL that is not that easy to grasp made the people hesitate.

Therefore we searched for some tool which allows us to define a contract in a more easy way. It would be nice if one could 'click together' or 'drag&drop' an endpoint through some UI and describe the details in a more convenient way. But until today we did not found anything that fits that need.

Long story short, it would be really helpful if you would provide such a tool. :)

[ingogriebsch]

Add @marcingrzejszczak and @TYsewyn to notify them.

[TYsewyn]

To add to this issue from our conversation on Gitter:

@TYsewyn: we're making plans to work on something that will enable you to specify your contract using a browser-based editor, which will then export it to groovy/yaml

[OlgaMaciaszek]

@ingogriebsch As I see in chat that @marcingrzejszczak is in favour of it, I'm adding it to the backlog.

In the meantime, I'm interested in how we could improve either the DSL or its docs to make it more usable. Honestly speaking, it always seemed quite intuitive to us, as it reflects the lingo usually used while talking about the HTTP/ messaging communications, but since the team has found it problematic, I guess there is room for improvement.

From the experience you've had, do you have any thoughts on how we could improve the dsl docs to make it easier for your teams to start working with it? As we are planning to do some work on our docs, it would be very helpful for us to get this kind of feedback.

[ingogriebsch]

Sorry @OlgaMaciaszek for coming back to you so late.

I do not know exactly how to describe it. I just looked again at the documentation (especially chapter 'Contract DSL'). The real problem is probably that colleagues are confronted with a new language and syntax and therefore have reservations. For many, it seems that one believes that one has understood the first simple examples, but then the implementation of a 'real' endpoint is difficult to handle.

Nonetheless, a few notes to the documentation:

• There is no reference to the full DSL. Of course, I can look into the spec jar and try to understand the code, but an overall view of the possibilities would be very helpful.

• Syntax is used in the examples, which will be explained in a later chapter. For example, 'value', 'consumer', 'producer' etc. This confuses reading more than it helps.

• Different spellings are used in the examples, but it is not explained which spellings are possible in principle. For example, 'status OK () and status 200'.

• Sometimes it is described that certain things can be configured. But it does not explain why you should do that. Why, for example Can I configure 'ignored' in a contract?

• The chapter 'dynamic properties' looks rather complicated at first. When do I use 'value'? And when do I use '$ (...)'? You're going to say 'that's easy because ...' but for someone who has never used DSL before, it all sounds confusing at first (but I also do not know how to describe / explain it more easily).

• A few basic hints or best practices would help a lot. Should I, for example, Use 'absent' if I want to express explicitly that a parameter is deliberately missing?

• Some things (such as 'consumer' and 'producer') are explained (again) in another chapter ('Spring Cloud Contract FAQ'). This information will probably be lost if I just look into chapter 'Contract DSL'.

I hope that my comments are helpful in any way. Please understand them as constructive criticism and not as derogatory remarks.

I find the topic very exciting and helpful and would therefore like to use it in our product and therefore convince our teams of the advantages. The more accessible the topic and the implementation, the easier I get people to use it. Therefore, I also believe that an editor would help a lot to lose the fear of contact. :)

/CC @marcingrzejszczak, @TYsewyn

[TYsewyn]

@ryandegruyter can you give us an update on the tool you were working on?

[ingogriebsch]

@TYsewyn @OlgaMaciaszek Any news on this topic? :)

[plamentotev]

In the meantime, I'm interested in how we could improve either the DSL or its docs to make it more usable. Honestly speaking, it always seemed quite intuitive to us, as it reflects the lingo usually used while talking about the HTTP/ messaging communications, but since the team has found it problematic, I guess there is room for improvement.

Having a schema for the YAML version would be really useful as it can serve both as reference documentation and many IDEs can provide auto-completion based on it.

[marcingrzejszczak]

Actually we do have it https://docs.spring.io/spring-cloud-contract/docs/current/reference/html/yml-schema.html and you can generate it yourself by running ./mvnw clean install -Pdocs -pl docs and the JSON schema is here docs/target/contract_schema.json