ADOC generation from contracts

[marcingrzejszczak]

DO NOT MERGE YET

Reason for the change

It can be useful to present in the form of documentation the contracts. The description field in the contract can provide an input to the scenario, whereas the contract speaks for itself. Obviously it's parsed so we can do something more descriptive. Also we can give the user an option to provide his own customizations.

Sample implementation

Running this test will result in creation of the following adoc

= Application Contracts

In the following document you'll be able to see all the contracts that are present for this application.

== Contracts

### shouldMarkClientAsNotFraud.groovy


            The following contract describes a situation where the user should be accepted in our system.
            It satisfies the ticket number ABC-123. For further information please contact the Product Owners
            John Doe and Jane Doe.

            Given:
                a user who wants to borrow an acceptable amount of money
            When:
                he is checked in the fraud system
            Then:
                the fraud check status should be "OK"
            And:
                the rejection reason should not contain any data


#### Contract structure

[source,java,indent=0]
----
package contracts

org.springframework.cloud.contract.spec.Contract.make {
            description('''
            The following contract describes a situation where the user should be accepted in our system.
            It satisfies the ticket number ABC-123. For further information please contact the Product Owners
            John Doe and Jane Doe.

            Given:
                a user who wants to borrow an acceptable amount of money
            When:
                he is checked in the fraud system
            Then:
                the fraud check status should be "OK"
            And:
                the rejection reason should not contain any data
            ''')
                request {
                    method 'PUT'
                    url '/fraudcheck'
                    body("""
                        {
                        "clientId":"${value(consumer(regex('[0-9]{10}')), producer('1234567890'))}",
                        "loanAmount":123.123
                        }
                    """
                    )
                    headers {
                        header('Content-Type', 'application/vnd.fraud.v1+json')
                    }

                }
            response {
                status 200
                body(
                        fraudCheckStatus: "OK",
                        rejectionReason: $(consumer(null), producer(execute('assertThatRejectionReasonIsNull($it)')))
                )
                headers {
                    header('Content-Type': value(
                            producer(regex('application/vnd.fraud.v1.json.*')),
                            consumer('application/vnd.fraud.v1+json'))
                    )
                }
            }

}

----

### shouldMarkClientAsFraud.groovy


            The following contract describes a situation where the user should NOT be accepted in our system.
            It satisfies the ticket number ABC-1234. For further information please contact the Product Owners
            John Doe and Jane Doe.

            Given:
                a user who wants to borrow a lot of money
            When:
                he applies for a loan
            Then:
                the loan should not be granted
            And:
                the user should marked as fraud


#### Contract structure

[source,java,indent=0]
----
package contracts

org.springframework.cloud.contract.spec.Contract.make {
            description('''
            The following contract describes a situation where the user should NOT be accepted in our system.
            It satisfies the ticket number ABC-1234. For further information please contact the Product Owners
            John Doe and Jane Doe.

            Given:
                a user who wants to borrow a lot of money
            When:
                he applies for a loan
            Then:
                the loan should not be granted
            And:
                the user should marked as fraud
            ''')
            request {
                method 'PUT'
                url '/fraudcheck'
                body([
                    clientId: value(consumer(regex('[0-9]{10}'))),
                    loanAmount: 99999
                    ])
                headers {
                    header('Content-Type', 'application/vnd.fraud.v1+json')
                }
            }
            response {
                status 200
                body([
                    fraudCheckStatus: "FRAUD",
                    rejectionReason: "Amount too high"
                ])
                headers {
                     header('Content-Type': value(
                             producer(regex('application/vnd.fraud.v1.json.*')),
                             consumer('application/vnd.fraud.v1+json'))
                     )
                }
            }
}
----

In target/generated-snippets.

CC @mminella @dussab @dsyer @spencergibb

[marcingrzejszczak]

A rendered example could look like this

[jedrzej-andrykowski]

Great idea! Very useful for non-technical persons such as analysts and testers. But one thing bothering me, that is this documentation doesn't doubles with documentation which is generated by Swagger? (it's known that many companies use it). Maybe it could be cool to add some integration with Swagger f.e. some annotations that add contracts documentation to Swagger output?

[marcingrzejszczak]

The difference between Swagger and this is that Swagger produces a technical description of the data model + response codes. Here you have scenarios. Each contract is a request / reply situation. E.g. we don't present all possible options of the request body. We present what kind of request / response is needed to achieve the following type of a response.

[jedrzej-andrykowski]

I think that contracts are so technical as the Swagger but additionally give you more real situation cases , not only dry request/response structured, nevertheless it looks quite good :)